第 5 章 基本内容

目录

5.1. 打包工作流
5.1.1. debhelper 软件包
5.2. 软件包名称和版本
5.3. 本土 Debian 软件包
5.4. debian/rules
5.4.1. dh
5.4.2. 简单的 debian/rules
5.4.3. 自定义 debian/rules
5.4.4. debian/rules 中的变量
5.4.5. 可重现的构建
5.5. debian/control
5.5.1. Debian 二进制软件包的拆分
5.5.1.1. debmake -b
5.5.1.2. 拆包的场景和例子
5.5.1.3. 库软件包名称
5.5.2. Substvar
5.5.3. binNMU 安全
5.6. debian/changelog
5.7. debian/copyright
5.8. debian/patches/*
5.8.1. dpkg-source -x
5.8.2. dquilt 和 dpkg-source
5.9. debian/upstream/signing-key.asc
5.10. debian/watch 和 DFSG
5.11. 其它 debian/* 文件
5.12. Debian 打包的定制化
5.13. 在版本控制系统中进行记录(标准)
5.14. 在版本控制系统中进行记录(备选方案)
5.15. Building package without extraneous contents
5.15.1. Fix by debian/rules clean
5.15.2. Fix using VCS
5.15.3. Fix by extend-diff-ignore
5.15.4. Fix by tar-ignore
5.16. 上游构建系统
5.16.1. Autotools
5.16.2. CMake
5.16.3. Python distutils
5.17. 调试信息
5.17.1. 新的 -dbgsym 软件包(Stretch 9.0 或更新)
5.18. 库软件包
5.18.1. 库符号
5.18.2. 库变迁
5.19. debconf
5.20. 多体系结构
5.20.1. The multiarch library path
5.20.2. The multiarch header file path
5.20.3. The multiarch *.pc file path
5.21. 编译加固
5.22. 持续集成
5.23. Bootstrapping
5.24. Bug reports

这里展示了 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 打包工作流可以概括为以下五步。

  1. 下载上游源码压缩包(tarball)并命名为 package-version.tar.gz 文件。
  2. 使上游提供的源码压缩包解压缩后的所有文件存储在 package-version/ 目录中。
  3. 上游的源码压缩包被复制(或符号链接)至一个特定的文件名 packagename_version.orig.tar.gz

    • 分隔 packageversion 的符号从 -(连字符)更改为 _(下划线)
    • 文件扩展名添加了 .orig 部分。
  4. Debian 软件包规范文件将被添加至上游源代码中,存放在 package-version/debian/ 目录下。

    • debian/* 目录下的必需技术说明文件:

      debian/rules
      构建 Debian 软件包所需的可执行脚本(参见 第 5.4 节 “debian/rules”
      debian/control
      软件包配置文件包含了源码包名称、源码构建依赖、二进制软件包名称、二进制软件包依赖,等等。(参见 第 5.5 节 “debian/control”
      debian/changelog
      Debian 软件包历史文件,其中第一行定义了上游软件包版本号和 Debian 修订版本号(参见 第 5.6 节 “debian/changelog”
      debian/copyright
      版权和许可证摘要信息(参看 第 5.7 节 “debian/copyright”
    • debian/* 下的可选配置文件(参见 第 5.11 节 “其它 debian/* 文件”):
    • package-version/ 目录中调用 debmake 命令将会提供这些配置文件的一套模板。

      • 必备的配置文件总会生成,无论是否提供 -x0 选项。
      • debmake 命令永远不会覆写任何已经存在的配置文件。
    • 这些文件必须手工编辑以达到理想状态。请使用“Debian 政策手册”和“Debian 开发者参考”作为编辑依据。
  5. dpkg-buildpackage 命令(通常由它的封装命令 debuildpdebuild 所使用)会在 package-version/ 目录中被调用,进而以调用 debian/rules 脚本的方式制作 Debian 源码包和二进制软件包。

    • 当前工作目录会被设为:$(CURDIR)=/path/to/package-version/
    • 使用 dpkg-source(1) 以“3.0 (quilt)”格式创建 Debian 源码包

      • package_version.orig.tar.gzpackage-version.tar.gz 的副本或符号链接)
      • package_version-revision.debian.tar.xzpackage-version/debian/* 的 tar 压缩包,即 tarball)
      • package_version-revision.dsc
    • 使用“debian/rules build”构建源代码并安装到 $(DESTDIR)

      • DESTDIR=debian/binarypackage/(单二进制包)
      • DESTDIR=debian/tmp/(多个二进制包)
    • 使用 dpkg-deb(1)、dpkg-genbuildinfo(1) 和 dpkg-genchanges(1) 创建 Debian 二进制软件包。

      • binarypackage_version-revision_arch.deb
      • ……(可能有多个 Debian 二进制包文件。)
      • package_version-revision_arch.changes
  6. 使用 lintian 命令检查 Debian 软件包的质量。(推荐)

  7. 使用 debsign 命令,用您的 GPG 私钥为 package_version-revision.dscpackage_version-revision_arch.changes 文件进行签名。
  8. 使用 dput 命令向 Debian 仓库上传一套 Debian 源码包和二进制软件包文件。

这里,请将文件名中对应的部分使用下面的方式进行替换:

  • package 部分替换为 Debian 源码包名称
  • binarypackage 部分替换为 Debian 二进制软件包名称
  • version 部分替换为上游版本号
  • revision 部分替换为 Debian 修订号
  • arch 部分替换为软件包对应架构
[提示] 提示

有很多种通过实践摸索而得到的补丁管理方法和版本控制系统的使用策略与技巧。您没有必要将它们全部用上。

[提示] 提示

在“Debian 开发者参考”一文的 第 6 章 最佳打包实践 部分有十分详尽的相关文档。请读一读这些内容。

如果所获取上游源代码的形式为 hello-0.9.12.tar.gz,您可以将 hello 作为上游源代码名称,并将 0.9.12 作为上游版本号。

debmake 的目的是为软件包维护者提供开始工作的模板文件。注释行以 # 开始,其中包含一些教程性文字。您在将软件包上传至 Debian 仓库之前必须删除或者修改这样的注释行。

许可证信息的提取和赋值过程应用了大量启发式操作,因此在某些情况下可能不会正常工作。强烈建议您搭配使用其它工具,例如来自 devscripts 软件包的 licensecheck 工具,以配合 debmake 的使用。

组成 Debian 软件包名称的字符选取存在一定的限制。最明显的限制应当是软件包名称中禁止出现大写字母。这里给出正则表达式形式的规则总结:

  • 上游软件包名称(-p):[-+.a-z0-9]{2,}
  • 二进制软件包名称(-b):[-+.a-z0-9]{2,}
  • 上游版本号(-u):[0-9][-+.:~a-z0-9A-Z]*
  • Debian 修订版本(-r): [0-9][+.~a-z0-9A-Z]*

请在“Debian 政策手册”的 第 5 章 - Control 文件及其字段 一节中查看其精确定义。

debmake 所假设的打包情景是相对简单的。因此,所有与解释器相关的程序都会默认为“Architecture: all”的情况。当然,这个假设并非总是成立。

您必须为 Debian 打包工作适当地调整软件包名称和上游版本号。

为了能有效地使用一些流行的工具(如 aptitude)管理软件包名称和版本信息,最好能将软件包名称保持在 30 字符以下;版本号和修订号加起来最好能不超过 14 个字符。[10]

为了避免命名冲突,对用户可见的二进制软件包名称不应选择任何常用的单词。

如果上游没有使用像 2.30.32 这样正常的版本编号方案,而是使用了诸如 11Apr29 这样包含日期、某些代号或者一个版本控制系统散列值等字符串作为版本号的一部分的话,请在上游版本号中将这些部分移除。这些信息可以稍后在 debian/changelog 文件中进行记录。如果您需要为软件设计一个版本字符串,可以使用 YYYYMMDD 格式,如 20110429 的字符串作为上游版本号。这样能保证 dpkg 命令在升级时能正确地确定版本的先后关系。如果您想要确保万一上游在未来重新采纳正常版本编号方案,例如 0.1 时能够做到顺畅地迁移,可以另行使用 0~YYMMDD 的格式,如 0~110429 作为上游版本号。

版本字符串可以按如下的方式使用 dpkg 命令进行比较。

$ dpkg --compare-versions ver1 op ver2

版本比较的规则可以归纳如下:

  • 字符串按照起始到末尾的顺序进行比较。
  • 字符比数字大。
  • 数字按照整数顺序进行比较。
  • 字符按照 ASCII 编码的顺序进行比较。

对于某些字符,如句点(.)、加号(+)和波浪号(~),有如下的特殊规则。

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.gzdpkg-buildpackage 获取到的时候,会出现意外地构建了本土 Debian 软件包的情况。这是新手常见的一个错误,通常是因构建中错误地在符号链接名称中使用了“-”字符而非正确的“_”字符。[译注:此处仍然假设打包的场景是已经获取或形成了名为 package-version.tar.gz 的上游源码 tarball。Debian 的打包工作很大程度上是以上游源码 tarball 作为基础的,这一点须时刻牢记在心。]

本土 Debian 软件包不对 上游代码Debian 的修改 进行区分,仅包含以下内容:

  • package_version.tar.gzpackage-version.tar.gz 文件的副本或符号链接,包含 debian/* 的各个文件。)
  • package_version.dsc

如果您需要手动创建本土 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 格式文件中的目的。

    • 这里的 deb 文件用于二进制的文件分发,并将被 dpkg 命令所使用以将软件安装至系统中。
  • dh 命令通常在 debian/rules 脚本中使用,用作构建系统的一个前端。
  • $(DESTDIR) 路径具体值依赖于构建的类型。

    • $(DESTDIR)=debian/binarypackage(单个二进制软件包)
    • $(DESTDIR)=debian/tmp(多个二进制软件包)

受益于 dh 命令对构建目标的抽象化 [11],一个符合 Debian 政策而支持所有必需目标(target)的 debian/rules 文件可以简单地写成如下形式[12]

简单的 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 目标所覆写。

构建的过程可以使用某些上游提供的接口进行定制化,如使用传递给标准的源代码构建系统的参数。这些构建系统包括但不限于:

  • configure
  • Makefile
  • setup.py,或
  • Build.PL

在这种情况下,您应该添加一个 override_dh_auto_build 目标并在其中执行“dh_auto_build -- 自定义参数” 的命令。这样可以在 dh_auto_build 默认传递的参数之后确保将用户给出的 自定义参数 继续传递给那些构建系统。

[提示] 提示

如果上文提到的构建系统命令已知得到了 dh_auto_build 命令的支持的话,请避免直接调用这些命令(而让 dh_auto_build 自动处理)。

debmake 命令所创建的初始模版文件除了应用了上文提到的简单 debian/rules 文件的优点外,同时为后续可能涉及的软件包加固等情景添加了一些额外的定制选项。您需要先了解整个构建系统背后的工作原理(参见 第 5.16 节 “上游构建系统”),之后才能收放自如地定制软件包来处理某些非常规的工作情况。

某些对自定义 debian/rules 有用的变量定义可以在 /usr/share/dpkg/ 目录下的文件中找到。比较重要的包括:

pkg-info.mk
DEB_SOURCEDEB_VERSIONDEB_VERSION_EPOCH_UPSTREAMDEB_VERSION_UPSTREAM_REVISIONDEB_VERSION_UPSTREAMDEB_DISTRIBUTION 变量。它们在向后移植(backport)支持等场景下能起到一定的作用。
vendor.mk
DEB_VENDORDEB_PARENT_VENDOR 变量,以及 dpkg_vendor_derives_from 宏。它们在系统提供方的支持方面(Debian、Ubuntu 等)有其特定用处。
architecture.mk
设置 DEB_HOST_* 和 DEB_BUILD_* 变量。除此之外存在一种替代方案,即直接调用 dpkg-architecture 来获取变量,一次调用查询得到一个变量值。如显式调用 dpkg-architecture 以获取必需变量的话,便不再需要在 debian/rules 中包含 architecture.mk 了(后者会引入全部架构相关的变量)。
buildflags.mk
设置 CFLAGSCPPFLAGSCXXFLAGSOBJCFLAGSOBJCXXFLAGSGCJFLAGSFFLAGSFCFLAGSLDFLAGS 这些构建标志(build flags)。

如果您希望在 debian/rules 中使用其中的某些变量,您可以将相关的代码复制到 debian/rules 文件中,或是重写一份简单的替代实现。总而言之请保持 debian/rules 文件尽量简单。

例如,您按如下的方法在 debian/rules 文件中添加内容,从而为 linux-any 目标架构添加额外的 CONFIGURE_FLAGS

DEB_HOST_ARCH_OS ?= $(shell dpkg-architecture -qDEB_HOST_ARCH_OS)
 ...
ifeq ($(DEB_HOST_ARCH_OS),linux)
CONFIGURE_FLAGS += --enable-wayland
endif
[提示] 提示

历史上对于 debhelper 兼容等级小于等于 8 的情况下,在 debian/rules 文件中包含 buildflags.mk 文件是很有用的,它可以合适地设置一些构建标志,如 CPPFLAGSCFLAGSLDFLAGS 等,同时保证对特定选项,如 DEB_CFLAGS_MAINT_APPENDDEB_BUILD_MAINT_OPTIONS 的合适处理。现在您应当使用的 debhelper 兼容等级大于等于 9,故如无特殊原因,请不要继续包含 buildflags.mk,请交由 dh 命令来处理和设置这些构建标志。

参见 第 5.20 节 “多体系结构”dpkg-architecture(1) 和 dpkg-buildflags(1)。

为了做到软件包可重现的构建,这里给出一些相关的建议。

dpkg-genbuildinfo(1) 生成的控制文件 source-name_source-version_arch.buildinfo 记录了构建环境信息。参见 deb-buildinfo(5)

debian/control 文件包含了由空行分隔的数块元信息数据。每块元数据按照如下的顺序定义了下面这些内容:

  • Debian 源码包的元信息数据
  • Debian 二进制软件包的元信息

参见“Debian 政策手册”中的 第 5 章 - Control 文件及其字段 一章以了解每块元信息的具体定义。

对行为良好的构建系统来说,对 Debian 二进制包的拆分可以由如下方式实现。

  • 为所有二进制软件包在 debian/control 文件中创建对应的二进制软件包条目。
  • 在对应的 debian/二进制软件包名.install 文件中列出所有文件的路径(相对于 debian/tmp 目录)。

请查看本指南中相关的例子:

debmake 命令的 -b 选项提供了一个符合直觉又灵活的功能,可以用来创建 debian/control 的初始模板文件,其中可以定义多个 Debian 二进制软件包,每节中含有如下字段:

  • Package:
  • Architecture:
  • Multi-Arch:
  • Depends:
  • Pre-Depends:

debmake 命令也会在每个适当的依赖字段中设置合适的变量替换占位符(substvars)。

我们在这里直接引用 debmake 手册页中的相关一部分内容。

-b "二进制软件包名[:type],…", --binaryspec "二进制软件包名[:type],…"

set the binary package specs by a comma separated list of binarypackage:type pairs, e.g., in the full form “foo:bin,foo-doc:doc,libfoo1:lib,libfoo-dev:dev” or in the short form, “-doc,libfoo1,libfoo-dev”.

这里,二进制软件包是二进制软件包名称,可选的类型应当从下面的类型值中进行选取:

  • bin:C/C++ 预编译 ELF 二进制代码软件包(any,foreign)(默认,别名:"",即,空字符串
  • data:数据(字体、图像、……)软件包(all,foreign)(别名:da
  • dev:库开发软件包(any,same)(别名:de
  • doc:文档软件包(all,foreign)(别名:do
  • lib:库软件包(any,same)(别名:l
  • perl:Perl 脚本软件包(all,foreign)(别名:pl
  • python:Python 脚本软件包(all,foreign)(别名:py
  • python3:Python3 脚本软件包(all,foreign)(别名:py3
  • ruby:Ruby 脚本软件包(all,foreign)(别名:rb
  • script:Shell 脚本软件包(all,foreign)(别名:sh

括号内成对的值,例如(any,foreign),是软件包的架构多架构(Multi-Arch)特性的值,它们将设置在 debian/control 文件中。

大多数情况下,debmake 命令可以有效地从二进制软件包的名称猜测出正确的类型。如果类型的值并不明显,程序将回退到将类型设置为bin。例如,libfoo 设置类型lib,而 font-bar 会令程序设置类型data,……

如果源码树的内容和类型的设置不一致,debmake 命令会发出警告。

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 a new SONAME major version which affects other packages.

库的二进制软件包将必须从 libfoo7 重命名为 libfoo8 以保持使用 unstable 套件的系统上所有依赖该库的软件包在上传了基于 libfoo-8.0.tar.gz 的新库后仍然能够正常运行。

[警告] 警告

如果这个二进制库软件包没有得到更名,许多使用 unstable 套件的系统上的各个依赖该库的软件包会在新的库包上传后立刻破损,即便立刻请求进行 binNMU 上传也无法避免这个问题。由于种种原因,binNMU 不可能在上传后立刻开始进行,故无法缓解问题。

-dev 软件包必须遵循以下命名规则:

[提示] 提示

如果包内数据文件编码方案有所变化(如,从 latin1 变为 utf-8),该场景应比照 API 变化做类似的考虑与处理。

参见 第 5.18 节 “库软件包”

debian/control 也定义了软件包的依赖关系,其中变量替换机制(substvar)的功能可以用来将软件包维护者从跟踪(大多数简单的)软件包依赖的重复劳动中解放出来。请参见 deb-substvars(5)。

debmake 命令支持下列变量替换指令:

  • ${misc:Depends},可用于所有二进制软件包
  • ${misc:Pre-Depends},可用于所有 multiarch 软件包
  • ${shlibs:Depends},可用于所有含有二进制可执行文件或库的软件包
  • ${python:Depends},可用于所有 Python 软件包
  • ${python3:Depends},可用于所有 Python3 软件包
  • ${perl:Depends},用于所有 Perl 软件包
  • ${ruby:Depends},用于所有 Ruby 软件包

For the shared library, required libraries found simply by "objdump -p /path/to/program | grep NEEDED" are covered by the shlib substvar.

对于 Python 和其它解释器来说,所需的模块通常由对包含类似“import”、“use”、“require”等等关键字的行进行解析,并会体现在各自对应的变量替换占位符所在位置上。

对其它没有部署属于自己范畴内的变量替换机制的情况,misc 变量替换占位符通常用来覆盖对应的依赖替换需求。

对 POSIX shell 程序来说,并没有简单的办法来验证其依赖关系,substvar 的变量替换也无法自动得出它们的依赖。

对使用动态加载机制,包括 GObject introspection 机制的库和模块来说,现在没有简单的方法可以检查依赖关系,变量替换机制也无法自动推导出所需的依赖。

一个 binNMU(二进制非维护者上传) 是为库迁移或其它目的所作的非维护者软件包上传。在一次 binNMU 上传中,只有“Architecture: any”的软件包会被重构建,其版本号会在末尾附加一个编号(例如,原来版本为 2.3.4-3,新上传的包版本会变成 2.3.4-3+b1)。所有“Architecture: all”的包将不会重新构建。

来自同一个源码包的各个二进制包如果在 debian/control 文件中有互相的依赖关系,这些二进制包通常情况下应当对 binNMU 是安全的(即,进行 binNMU 不会破坏依赖关系)。然而,在“Architecture: any”和“Architecture: all”的软件包同时由同一源码包产出,且互相之间有依赖关系时,需要小心对待所依赖的版本,必要时应做出调整。

  • Architecture: any”的软件包依赖于“Architecture: anyfoo 软件包

    • Depends: foo (= ${binary:Version})
  • Architecture: any”的软件包依赖于“Architecture: allbar 软件包

    • Depends: bar (= ${source:Version}
  • Architecture: all”的软件包依赖于“Architecture: anybaz 软件包

    • Depends: baz (>= ${source:Version}), baz (<< ${source:Upstream-Version}.0~)

debian/changelog 文件记录了 Debian 软件包的历史并在其第一行定义了上游软件包的版本和 Debian 修订版本。所有改变的内容应当以明确、正式而简明的语言风格进行记录。

  • 即便您在自己独立进行软件包上传,您也必须记录所有较重要、用户可见的变更,例如:

    • 安全相关的漏洞修复。
    • 用户界面变动。
  • 如果您需要他人协助您进行上传,您应当更详尽地记录变更内容,包括所有打包相关的变动,从而方便他人对您的软件包进行审查。

    • 协助上传的人员不应该也通常不会猜测您没有写出来的想法,所以请认真书写变更信息。
    • 通常来说,协助您上传的人的时间比您的时间更宝贵。

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.

通常使用 debchange 命令(它具有一个别名,即 dch)对其进行编辑。

[提示] 提示

您也可以手动使用任何文本编辑器修改 debian/changelog 文件,只要您能够遵循 debchange 命令所使用的特定文本排版格式即可。

[提示] 提示

debian/changelog 文件使用的日期字符串可以使用“LC_ALL=C date -R”命令手动生成。

This is installed in the /usr/share/doc/binarypackage directory as changelog.Debian.gz by the dh_installchangelogs command.

上游的变更日志则会安装至 /usr/share/doc/binarypackage 目录中,文件名为 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.

当您完成了主要打包工作并验证了其质量之后,请考虑运行“dch -r”命令并将最终完成的 debian/changelog 文件中发行版(distribution)部分进行设置,通常该字段应当使用 unstable[13] 如果您的打包是一次向后移植(backports)、是安全更新或是对长期支持版的上传等等其它情况,请使用相应合适的发行版名称。

Debian 以十分严肃的态度对待版权和许可证信息。“Debian 政策手册”强制规定软件包的 debian/copyright 文件中需要提供相关信息的摘要。

您应当按照 机器可解析的 debian/copyright 文件(DEP-5)对其进行排版。

[小心] 小心

这里的 debian/copyright 文件中描述的许可证信息匹配信息应当合适地进行排序,以确保越宽泛的文件匹配越靠前。请参见 第 6.4 节 “debmake -k”

debmake 命令会以扫描整个源码树的方式创建初步的、兼容 DEP-5 的模板文件。它会内部调用许可证检查工具来对许可证文本进行分类。[14]

除非明确指定(有些严格过头的) -P 选项,debmake 命令会为了实用性而跳过对自动生成的文件的检查与报告,默认它们采用宽松的许可证。

[注意] 注意

如果您发现了这个许可证检查工具存在一些问题,请向 debmake 软件包提交缺陷报告并提供包含出现问题的许可证和版权信息在内的相关文本内容。

[注意] 注意

debmake 命令专注于在创建 debian/copyright 模板时聚合相同的授权和许可证信息并收录其详细内容。为了在有限的时间内尽可能完成工作,工具将只会提取文件中第一块看起来像授权文本或许可证声明的部分。因此,生成的许可证信息可能并不完美。请同时考虑使用其它工具,如 licensecheck 辅助进行检查。

[提示] 提示

我们强烈推荐您使用 licensecheck(1) 命令再次检查源码许可证的状态,并在有必要的情况下进行人工代码审查。

构建过程开始之前,debian/patches/ 目录内的 -p1 等级的补丁将会按照在 debian/patches/series 文件中指定的顺序依次应用于上游代码树中。

[注意] 注意

本土 Debian 软件包(参见 第 5.3 节 “本土 Debian 软件包”)将不使用这些文件。

要准备这一系列 -p1 等级的补丁,有几种不同的方式可供您选择。

  • diff 命令

    • 参见 第 4.8.1 节 “使用 diff -u 处理补丁”
    • 原始但万能的方法

      • 补丁的来源多种多样,它可以来自其它发行版、邮件列表中的帖文或是来自上游 git 仓库的拣选补丁,由“git format-patches”生成
    • 不涉及 .pc/ 目录的问题
    • 不修改上游源代码树
    • 手工更新 debian/patches/series 文件
  • dquilt 命令

    • 参见 第 3.4 节 “quilt”
    • 基本的便利方案
    • 会以合适方式生成 .pc/ 目录及其中的数据
    • 会修改上游源代码树
  • dpkg-source --commit”命令

  • dpkg-buildpackage 自动生成补丁

  • gbp-pq 命令

    • 配合 git-buildpackage 工具的基本 git 工作流
    • 不涉及 .pc/ 目录的问题
    • 在可丢弃分支上保存经过修改的上游源码树(patch-queue/master
    • 在 Debian 分支中(常见为 master 分支)存储未经修改的源码树
  • gbp-dpm 命令

    • 配合 git-dpm 软件包的更细致的 git 工作流
    • 不涉及 .pc/ 目录的问题
    • 在补丁分支中(通常命名为 patched/随便啥名字)存储经过修改的上游源码树
    • 在 Debian 分支中(通常命名为 master/随便啥名字)存储未经修改的上游源码树

无论这些补丁的来源如何,都建议使用兼容于 DEP-3 的头部信息对其进行标记。

[提示] 提示

dgit 软件包提供了另外一套直接使用 git 集成操作 Debian 软件包仓库的工具。

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.

在使用 dpkg-source 命令时,补丁应当能够干净地进行应用。因此在补丁行数出现偏移或者其它情况出现时,您不能直接将旧补丁原封不动地复制到新版上游发布对应打包版本的目录中。

与此相对的是 dquilt 命令(参见 第 3.4 节 “quilt”)对补丁的处理更加宽容。您可以调用 dquilt 命令对补丁进行正常化。

 $ while dquilt push; do dquilt refresh ; done
 $ dquilt pop -a

使用 dpkg-source 命令比起使用 dquilt 命令来说存在一大优势:dquilt 命令无法自动处理二进制文件出现变更的情况,而 dpkg-source 命令能够探测出现内容变动的二进制文件,并将其列入 debian/source/include-binaries 文件以便在 Debian 打包用压缩包中将文件囊括其中。

某些软件包由 GPG 密钥进行了签名。

例如,GNU hello 可使用 HTTP 协议从 https://ftp.gnu.org/gnu/hello/ 下载。它含有以下文件:

  • hello-version.tar.gz(上游源代码)
  • hello-version.tar.gz.sig(分离的签名)nature)

我们现在来选择最新的版本套装。

$ 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

如果您从邮件列表获知上游维护者所使用的 GPG 公钥信息,请将它作为 debian/upstream/signing-key.asc 文件进行存储。否则,请使用 hkp 公钥服务器并经由您的信任网进行验证。

$ 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
[提示] 提示

如果您的网络环境阻挡了对 HKP 11371 端口的访问,请考虑使用“hkp://keyserver.ubuntu.com:80”。

在确认密钥身份 80EE4A00 值得信任之后,应当下载其公钥并将其保存在 debian/upstream/signing-key.asc 文件中。

$ gpg --armor --export 80EE4A00 >debian/upstream/signing-key.asc

之后,应相应地在 debian/watch 文件中做如下的修改。

version=4
pgpsigurlmangle=s/$/.sig/  https://ftp.gnu.org/gnu/hello/ hello-(\d[\d.]*)\.tar\.(?:gz|bz2|xz)

现在 uscan 命令会在扫描时自动使用 GPG 签名验证上游源码包的真实性。

Debian 严肃地对待软件自由,遵循 Debian 自由软件指导方针(DFSG)

在使用 uscan 命令来更新 Debian 打包所用代码时,上游源码包(tarball)中不符合Debian 自由软件指导方针(DFSG)的部分可以利用该工具简单地进行移除。

  • debian/copyright 文件中的 Files-Excluded 一节中列出需要移除的文件。
  • debian/watch 文件中列出下载上游源码包(tarball)所使用的 URL。
  • 运行 uscan 命令以下载新的上游源码包(tarball)。

    • 作为替代方案,您也可以使用“gbp import-orig --uscan --pristine-tar”命令。
  • 最后得到 tarball 的版本编号会附加一个额外的后缀 +dfsg

另外也可以添加一些可选的配置文件并放入 debian/ 目录。它们大多用于控制由 debhelper 软件包提供的 dh_* 命令的行为,但也有一些文件会影响 dpkg-sourcelintiangbp 这些命令。

[提示] 提示

请检查 debhelper(7) 的内容以了解当前可用的 dh_* 命令列表。

这些 debian/binarypackage.* 的文件提供了设置文件安装路径的强大功能。即使上游源代码没有构建系统,这个软件依然可以利用这里提到的这些文件来进行打包。请参考 第 8.2 节 “No Makefile (shell, CLI)” 的示例。

The "-x[1234]" superscript notation that appears in the following list indicates the minimum value for the debmake -x option that will generate the associated template file. See 第 6.6 节 “debmake -x” or debmake(1) for details.

下面按照字母表顺序列出一些值得注意的可选配置文件。

binarypackage.bug-control -x3
将安装至 binarypackage 软件包的 usr/share/bug/binarypackage/control 位置。另请参考第 5.24 节 “Bug reports”
binarypackage.bug-presubj -x3
将安装至 binarypackage 软件包的 usr/share/bug/binarypackage/presubj 位置。另请参考第 5.24 节 “Bug reports”
binarypackage.bug-script -x3
将安装至 binarypackage 软件包的 usr/share/bug/binarypackage or usr/share/bug/binarypackage/script 位置。另请参考第 5.24 节 “Bug reports”
binarypackage .bash-completion

列出需要安装的 bash 补全脚本。

需要在构建环境和用户环境内均安装 bash-completion 软件包。

另请参考dh_bash-completion(1)。

clean -x2

列出(构建前)未被 dh_auto_clean 命令清理,且需要手工清理的文件。

另请参考 dh_auto_clean(1) 和 dh_clean(1)。

compat -x1

Set the debhelper compatibility level (currently, “9”).

See “COMPATIBILITY LEVELS” in debhelper(8).

binarypackage.conffile

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 not to be conffiles, keeping the dpkg command happy and quiet.

  • Create a symlink under the /etc directory pointing to a file under the /var directory generated by the maintainer scripts.
  • Create a file generated by the maintainer scripts under the /etc directory.

See dh_installdeb(1).

binarypackage.config
This is the debconf config script used for asking any questions necessary to configure the package. See 第 5.19 节 “debconf”.
binarypackage.cron.hourly -x3

Installed into the etc/cron/hourly/binarypackage file in binarypackage.

See dh_installcron(1) and cron(8).

binarypackage.cron.daily -x3

Installed into the etc/cron/daily/binarypackage file in binarypackage.

See dh_installcron(1) and cron(8).

binarypackage.cron.weekly -x3

Installed into the etc/cron/weekly/binarypackage file in binarypackage.

See dh_installcron(1) and cron(8).

binarypackage.cron.monthly -x3

Installed into the etc/cron/monthly/binarypackage file in binarypackage.

See dh_installcro*(1) and cron(8).

binarypackage.cron.d -x3

Installed into the etc/cron.d/binarypackage file in binarypackage.

See dh_installcron(1), cron(8), and crontab(5).

binarypackage.default -x3

If this exists, it is installed into etc/default/binarypackage in binarypackage.

参见 dh_installinit(1)。

binarypackage.dirs -x3

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.

binarypackage.doc-base -x2

Installed as the doc-base control file in binarypackage.

See dh_installdocs(1) and Debian doc-base Manual provided by the doc-base package.

binarypackage.docs -x2

List documentation files to be installed in binarypackage.

参见 dh_installdocs(1)。

binarypackage.emacsen-compat -x3

Installed into usr/lib/emacsen-common/packages/compat/binarypackage in binarypackage.

参见 dh_installemacsen(1)。

binarypackage.emacsen-install -x3

Installed into usr/lib/emacsen-common/packages/install/binarypackage in binarypackage.

参见 dh_installemacsen(1)。

binarypackage.emacsen-remove -x3

Installed into usr/lib/emacsen-common/packages/remove/binarypackage in binarypackage.

参见 dh_installemacsen(1)。

binarypackage.emacsen-startup -x3

Installed into usr/lib/emacsen-common/packages/startup/binarypackage in binarypackage.

参见 dh_installemacsen(1)。

binarypackage.examples -x2

List example files or directories to be installed into usr/share/doc/binarypackage/examples/ in binarypackage.

See dh_installexamples(1).

gbp.conf

If this exists, it functions as the configuration file for the gbp command.

See gbp.conf(5), gbp(1), and git-buildpackage(1).

binarypackage.info -x2

List info files to be installed in binarypackage.

See dh_installinfo(1).

binarypackage.init -x3

Installed into etc/init.d/binarypackage in binarypackage.

参见 dh_installinit(1)。

binarypackage.install -x2

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).

license-examples/* -x4

These are copyright file examples generated by the debmake command. Use these as the reference for making the copyright file.

Please make sure to erase these files.

binarypackage.links -x2

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.

See dh_link(1).

binarypackage.lintian-overrides -x3

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.

manpage.* -x3

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 a manpage, use manpage.asciidoc or manpage.1 as the starting point.

binarypackage.manpages -x2

List man pages to be installed.

See dh_installman(1).

binarypackage.menu (deprecated, no more installed)

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).

NEWS

Installed into usr/share/doc/binarypackage/NEWS.Debian.

See dh_installchangelogs(1).

patches/*

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.

patches/series -x1
The application sequence of the patches/* patch files.
binarypackage.preinst -x2 , binarypackage.postinst -x2 , binarypackage.prerm -x2 , binarypackage.postrm -x2

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 in the “Debian Policy Manual”.

See also debconf-devel(7) and 3.9.1 Prompting in maintainer scripts in the “Debian Policy Manual”.

README.Debian -x1

Installed into the first binary package listed in the debian/control file as usr/share/doc/binarypackage/README.Debian.

参见 dh_installdocs(1)。

This file provides the information specific to the Debian package.

binarypackage.service -x3

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).

source/format -x1

The Debian package format.

  • Use “3.0 (quilt)” to make this non-native package (recommended)
  • Use “3.0 (native)” to make this native package

See “SOURCE PACKAGE FORMATS” in dpkg-source(1).

source/lintian-overrides or source.lintian-overrides -x3

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).

source/local-options -x1

The dpkg-source command uses this content as its options. Notable options are:

  • unapply-patches
  • abort-on-upstream-changes
  • auto-commit
  • single-debian-patch

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).

source/local-patch-header

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).

binarypackage.symbols -x2

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 节 “库符号”..

binarypackage.templates
This is the debconf templates file used for asking any questions necessary to configure the package. See 第 5.19 节 “debconf”.
tests/control
This is the RFC822-style test meta data file defined in DEP-8. See autopkgtest(1) and 第 5.22 节 “持续集成”.
TODO

Installed into the first binary package listed in the debian/control file as usr/share/doc/binarypackage/TODO.Debian.

参见 dh_installdocs(1)。

binarypackage.tmpfile -x3

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).

binarypackage.upstart -x3

If this exists, it is installed into etc/init/package.conf in the package build directory. (deprecated)

See dh_installinit(1) and 第 8.1 节 “挑选最好的模板”.

watch -x1

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 和 DFSG” and uscan(1).

Here are a few reminders for the above list.

  • For a single binary package, the binarypackage. part of the filename in the list may be removed.
  • For a multi binary package, a configuration file missing the binarypackage. part of the filename is applied to the first binary package listed in the debian/control.
  • When there are many binary packages, their configurations can be specified independently by prefixing their name to their configuration filenames such as package-1.install, package-2.install, etc.
  • Some template configuration files may not be created by the debmake command. In such cases, you need to create them with an editor.
  • Unusual configuration template files generated by the debmake command with an extra .ex suffix need to be activated by removing that suffix.
  • Unused configuration template files generated by the debmake command should be removed.
  • Copy configuration template files as needed to the filenames matching their pertinent binary package names.

我们来重新归纳一下 Debian 打包定制化的相关内容。

All customization data for the Debian package resides in the debian/ directory. A simple example is given in 第 4.6 节 “第三步:编辑模板文件”. Normally, this customization involves a combination of the following:

When these are not sufficient to make a good Debian package, modifications 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/*”). 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 future upgrades in this way.

[注意] 注意

Send the patch addressing the root cause to the upstream maintainer if it is useful to the upstream.

通常情况下,Debian 打包活动使用 Git 作为版本控制系统(VCS)进行记录;通常会用到下列的分支:

  • master 分支

    • 记录用于 Debian 打包的源代码树。
    • 源码树的上游部分将照原样记录,不做修改。
    • Debian 打包中需要对上游源代码所作的修改记录在 debian/patches/ 目录中,以 -p1 等级的补丁形式存在。
  • upstream 分支

    • 记录从上游发布的 tarball(源码压缩文件)解压缩所得到的源代码树。
[提示] 提示

添加一个 .gitignore 文件并将 .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 分支

    • 记录用于 Debian 打包的源代码树。
    • The upstream portion of the source tree is recorded with modifications for the Debian packaging.
  • upstream 分支

    • 记录从上游发布的 tarball(源码压缩文件)解压缩所得到的源代码树。

Adding a few extra files in the 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, …) 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.

[提示] 提示

debian/source/local-optionsdebian/source/local-patch-header 文件只用于在版本控制系统中记录信息。它们不应包含在 Debian 源码包中。

There are a few cases which cause the inclusion of undesirable contents in the generated Debian source package.

  • The upstream source tree may be placed under the version control system. When the package is rebuilt from this source tree, the generated Debian source package contains extraneous contents from the version control system files.
  • The upstream source tree may contain some auto-generated files. When the package is rebuilt from this source tree, the generated Debian source package contains extraneous contents from the auto-generated files.

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 undesirable contents.

Upstream build systems are designed to go through several steps to install generated binary files to the system from the source distribution.

[提示] 提示

Before attempting to make a Debian package, you should become familiar with the upstream build system of the upstream source code and try to build it.

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

Packaging library software requires you to perform much more work than usual. Here are some reminders for packaging library software:

Before packaging shared library software, see:

如需研究其历史背景,请参见:

The symbols support in dpkg introduced in 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 with each symbol.

An 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.

    • Alternatively, the mc command may be used to extract the DEBIAN/symbols file.
  • Copy it to the debian/binarypackage.symbols file.

    • If this is the first package, use an empty content file instead.
  • Build the binary package.

    • If the dpkg-gensymbols command warns about some new symbols:

      • Extract the updated DEBIAN/symbols file with the “dpkg-deb -e” command.
      • Trim the Debian revision such as -1 in it.
      • Copy it to the debian/binarypackage.symbols file.
      • 重新构建二进制软件包。
    • If the dpkg-gensymbols command does not warn about new symbols:

      • You are done with the library packaging.

For the details, you should read the following primary references.

Yous should also check:

[提示] 提示

For C++ libraries and other cases where the tracking of 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.

The debconf package enables us to configure packages during their installation in 2 main ways:

  • non-interactively from the debian-installer pre-seeding.
  • interactively from the menu interface (dialog, gnome, kde, …)

    • the package installation: invoked by the dpkg command
    • the installed package: invoked by the dpkg-reconfigure command

All user interactions for the package installation must be handled by this debconf system using the following files.

  • debian/binarypackage.config

    • This is the debconf config script used for asking any questions necessary to configure the package.
  • debian/binarypackage.template

    • This is the debconf templates file used for asking any questions necessary to configure the package.
  • package configuration scripts

    • debian/binarypackage.preinst
    • debian/binarypackage.prerm
    • debian/binarypackage.postinst
    • debian/binarypackage.postrm

See dh_installdebconf(1), debconf(7), debconf-devel(7) and 3.9.1 Prompting in maintainer scripts in the “Debian Policy Manual”.

Multiarch support for cross-architecture installation of binary packages (particularly i386 and amd64, but also other combinations) in the dpkg and apt packages introduced in Debian wheezy (7.0, May 2013), demands that we pay extra attention to packaging.

You should read the following references in detail.

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 required internally by debhelper scripts is implicitly set in themselves. The maintainer doesn’t need to worry.
  • The <triplet> value used in override_dh_* target scripts must be explicitly set in the debian/rules file by the maintainer. The <triplet> value is stored in the $(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 following 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 the Filesystem Hierarchy Standard to use /usr/lib/<triplet>/ instead of /usr/lib<qual>/ (e.g., /lib32/ and /lib64/) to support a multiarch library.


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.

  • If “./configure” is used in the override_dh_auto_configure target in debian/rules, make sure to replace it with “dh_auto_configure --” while re-targeting the install path from /usr/lib/ to /usr/lib/$(DEB_HOST_MULTIARCH)/.
  • Replace all occurrences of /usr/lib/ with /usr/lib/*/ in debian/foo.install files.

All files installed simultaneously as the multiarch package to the same file path should have exactly the same file content. You must be careful with 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, a 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 a 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 a 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 shared library files in another path, the GCC option -l must be set by the pkg-config command to make them load properly.

The compiler hardening support spreading for Debian jessie (8.0, TBA) demands that we pay extra attention to the packaging.

You should read the following references in detail.

debmake 命令会向 debian/rules 文件中按需添加 DEB_BUILD_MAINT_OPTIONSDEB_CFLAGS_MAINT_APPENDDEB_LDFLAGS_MAINT_APPEND 的项目(参见 第 4 章 简单例子dpkg-buildflags(1))。

DEP-8 defines the debian/tests/control file as the RFC822-style test metadata file for 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 autopkgtest command 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.

  • The debci package: CI platform on top of the autopkgtest package
  • The jenkins package: generic CI platform

Debian cares about supporting new ports or flavours. The new ports or flavours require bootstrapping operation for the cross-build of the 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 foo build depends on a package bar with deep build dependency chains but bar is only used in the test target in foo, you can safely mark the bar with <!nocheck> in the Build-depends of foo to avoid build loops.

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-controlusr/share/bug/binarypackage/control

    • This file contains some directions such as redirecting the bug report to another package.
  • debian/binarypackage.bug-presubjusr/share/bug/binarypackage/presubj

    • This file is displayed to the user by the reportbug command.
  • debian/binarypackage.bug-scriptusr/share/bug/binarypackage or usr/share/bug/binarypackage/script

    • The reportbug command runs this script to generate a template file for the bug report.

See dh_bugfiles(1) and reportbug’s Features for Developers

[提示] 提示

If you always remind the bug reporter of something or ask them about their situation, use these files to automate it.



[10] 对九成以上的软件包来说,软件包名称都不会超过 24 个字符;上游版本号通常不超过 10 个字符,而 Debian 修订版本号也通常不超过 3 个字符。

[11] 这个简化形式在 debhelper 软件包第七版或更新的版本中可用。本指南内容假设您在使用 debhelper 第九版或更新的版本。

[12] debmake 命令会产生稍微复杂一些的 debian/rules 文件。虽然如此,其核心结构没有什么变化。

[13] 如果您在使用 vim 编辑器,请确保使用“:wq”命令对内容进行保存。

[14] 程序以前会在内部调用来自 devscripts 软件包的 licensecheck 命令来进行检查。现在的 licensecheck 命令由独立的 licensecheck 软件包所提供,相较从前的实现也有了较大的改进。

[15] 该文档是在 symbols 文件被引入之前写成的。

[16] The strong preference is to use the SONAME versioned -dev package names over the single -dev package name in Chapter 6. Development (-DEV) packages, which 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.

[17] This path is compliant with 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."