Chapter 6. Basics for packaging

Table of Contents

6.1. 打包工作流
6.2. debhelper package
6.3. 软件包名称和版本
6.4. 原生 Debian 软件包
6.5. debian/rules file
6.6. debian/control file
6.7. debian/changelog file
6.8. debian/copyright file
6.9. debian/patches/* files
6.10. debian/source/include-binaries file
6.11. debian/watch file
6.12. debian/upstream/signing-key.asc file
6.13. debian/salsa-ci.yml file
6.14. Other debian/* files

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

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

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

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

    • The current directory is set as: CURDIR=/path/to/package-version/
    • Create the Debian source package in the Debian source format 3.0 (quilt) using dpkg-source(1)

      • package_version.orig.tar.gz (copy or symlink of package-version.tar.gz)
      • package_version-revision.debian.tar.xz (tarball of debian/ found in package-version/)
      • package_version-revision.dsc
    • Build the source using debian/rules build into $(DESTDIR)

      • DESTDIR=debian/binarypackage/ for single binary package [11]
      • DESTDIR=debian/tmp/ for multi binary package
    • 使用 dpkg-deb(1)、dpkg-genbuildinfo(1) 和 dpkg-genchanges(1) 创建 Debian 二进制软件包。

      • binarypackage_version-revision_arch.deb
      • …​ (There may be multiple Debian binary package files.)
      • package_version-revision_arch.changes
      • package_version-revision_arch.buildinfo
  6. 使用 lintian 命令检查 Debian 软件包的质量。(推荐)

  7. 通过手工安装和运行软件包里的程序,来测试生成的 Debian 二进制软件包的可用性。
  8. After confirming the goodness, prepare files for the normal source-only upload to the Debian archive.
  9. Sign the Debian package file with the debsign command using your private GPG key.

    • Use debsign package_version-revision_source.changes (normal source-only upload situation)
    • Use debsign package_version-revision_arch.changes (exceptional binary upload situation such as NEW uploads, and security uploads) files for the binary Debian package upload.
  10. Upload the set of the Debian package files with the dput command to the Debian archive.

    • Use dput package_version-revision_source.changes (source-only upload)
    • Use dput package_version-revision_arch.changes (binary upload)

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.

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

  • package 部分替换为 Debian 源码包名称
  • binarypackage 部分替换为 Debian 二进制软件包名称
  • version 部分替换为上游版本号
  • revision 部分替换为 Debian 修订号
  • the arch part with the package architecture (e.g., amd64)

参见 Source-only uploads

[Tip]Tip

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

[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 打包工作流可以组织成一个简单的模块化工作流,如下所示:

  • 使用 dh 命令以自动调用来自 debhelper 软件包的许多实用脚本,以及
  • 使用 debian/ 目录下的声明式配置文件配置它们的行为。

您几乎总是应当将 debhelper 列为您的软件包的构建依赖之一。本文档在接下来的内容中也假设您正在使用一个版本足够新的 debhelper 协助进行打包工作。

[Note]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]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 软件包名称的字符选取存在一定的限制。最明显的限制应当是软件包名称中禁止出现大写字母。这里给出正则表达式形式的规则总结:

  • Upstream package name (-p): [-+.a-z0-9]{2,}
  • Binary package name (-b): [-+.a-z0-9]{2,}
  • Upstream version (-u): [0-9][-+.:~a-z0-9A-Z]*
  • Debian revision (-r): [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

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

  • 字符串按照起始到末尾的顺序进行比较。
  • 字符比数字大。
  • 数字按照整数顺序进行比较。
  • 字符按照 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

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]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 的修改 进行区分,仅包含以下内容:

  • package_version.tar.gz (copy or symlink of package-version.tar.gz with debian/* files.)
  • package_version.dsc

If you need to create a native Debian package, create it in the Debian source format 3.0 (native) using dpkg-source(1).

[Tip]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]

  • dh clean:清理源码树中的文件。
  • dh build:在源码树中进行构建
  • dh build-arch:在源码树中构建架构相关的软件包
  • dh build-indep:在源代码中构建架构无关的软件包
  • dh install:将二进制文件安装至 $(DESTDIR)
  • dh install-arch:为架构相关的软件包将二进制文件安装至 $(DESTDIR)
  • dh install-indep:为架构无关的软件包将二进制文件安装进入 $(DESTDIR)
  • dh binary:产生 deb 文件
  • dh binary-arch:为架构相关的软件包产生 deb 文件
  • dh binary-indep:为架构无关的软件包产生 deb 文件

Here, $(DESTDIR) path depends on the build type.

  • DESTDIR=debian/binarypackage/ for single binary package [15]
  • DESTDIR=debian/tmp/ for multi binary package

See Section 8.2, “Customized debian/rules and Section 8.3, “Variables for debian/rules for customization.

[Tip]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 文件包含了由空行分隔的数块元信息数据。每块元数据按照如下的顺序定义了下面这些内容:

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

See Chapter 5 - Control files and their fields” of the Debian Policy Manual for the definition of each meta data.

[Note]Note

The debmake command sets the debian/control file with Build-Depends: debhelper-compat (= 13) to set the debhelper compatibility level.

[Tip]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.

  • This should be edited using the debchange command (alias dch).
  • This defines the upstream package version and the Debian revision in its first line.
  • The changes need to be documented in the specific, formal, and concise style.

    • If Debian maintainer modification fixes reported bugs, add Closes: #<bug_number> to close those bugs.
  • 即便您在自己独立进行软件包上传,您也必须记录所有较重要、用户可见的变更,例如:

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

    • The sponsor shouldn’t be forced to second guess your thought behind your package.
    • 通常来说,协助您上传的人的时间比您的时间更宝贵。

After finishing your packaging and verifying its quality, please execute the dch -r command and save the finalized debian/changelog file with the suite normally set to unstable. [16] If you are packaging for backports, security updates, LTS, etc., please use the appropriate distribution names instead.

debmake 命令会创建初始的模板文件,其中带有上游软件包版本和 Debian 打包修订编号。发行版部分被设置为 UNRELEASED 以避免半成品不小心被上传进入 Debian 仓库。

[Tip]Tip

The date string used in the debian/changelog file can be manually generated by the LC_ALL=C date -R command.

[Tip]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 程序自动进行搜索和处理的;它会使用大小写不敏感的搜索方式寻找上游代码中特定名称的文件,如 changelogchangeschangelog.txtchanges.txthistoryhistory.txtchangelog.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]Caution

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

[Note]Note

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

As demonstrated in Section 5.9, “Step 3 (alternatives): Modification to the upstream source””, the debian/patches/ directory holds

  • patch-file-name.patch files providing -p1 patches and
  • the series file which which defines how these patches are applied.

See how these files are used in:

[Note]Note

Header texts of these patches should conform to DEP-3.

[Note]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:

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

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

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]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-sourcelintiangbp 这些命令。

[Tip]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:

  • The "-x[01234]" superscript notation that appears in the following list indicates the minimum value for the debmake -x option that generates the associated template file. See Section 15.9, “debmake -x” or debmake(1) for details.
  • 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.
  • debmake 可能没有自动生成某些模板配置文件。如遇到这种情况,您可以使用文本编辑器手动创建缺失的文件。
  • Some configuration template files generated by the debmake command with an extra .ex suffix need to be activated by removing that suffix.
  • 您应当删除 .ex 命令生成但对您无用的配置模板文件。
  • 请按需复制配置模板文件以匹配其对应的二进制包名称以及您的需求。

    binarypackage.bug-control -x3
    将安装至 binarypackage 软件包的 usr/share/bug/binarypackage/control 位置。另请参考Section 8.11, “错误报告”
    binarypackage.bug-presubj -x3
    将安装至 binarypackage 软件包的 usr/share/bug/binarypackage/presubj 位置。另请参考Section 8.11, “错误报告”
    binarypackage.bug-script -x3
    将安装至 binarypackage 软件包的 usr/share/bug/binarypackage or usr/share/bug/binarypackage/script 位置。另请参考Section 8.11, “错误报告”
    binarypackage.bash-completion -x3

    List bash completion scripts to be installed.

    The bash-completion package is required for both build and user environments.

    另请参考dh_bash-completion(1)。

    clean -x2

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

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

    compat -x4

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

    binarypackage.conffiles -x3

    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 命令处理软件包时给出不必要的处理选项。

    • /etc 目录下创建一个符号链接,指向 /var 目录下的某些文件;实际存在的文件则使用维护者脚本(maintainer script)予以创建。
    • 使用维护者脚本(maintainer script)在 /etc 目录下创建并维护配置所需的文件。

    另请参考 dh_installdeb(1)。

    binarypackage.config -x3
    这是 debconf config 脚本,用来在配置软件包时向用户询问任何必需的问题。另请参见Section 9.22, “debconf
    binarypackage.cron.hourly -x3

    安装至 binarypackage 包内的 etc/cron/hourly/binarypackage 文件。

    另请参见 dh_installcron(1) 和 cron(8)。

    binarypackage.cron.daily -x3

    安装至 binarypackage 包内的 etc/cron/daily/binarypackage 文件。

    另请参见 dh_installcron(1) 和 cron(8)。

    binarypackage.cron.weekly -x3

    安装至 binarypackage 包内的 etc/cron/weekly/binarypackage 文件。

    另请参见 dh_installcron(1) 和 cron(8)。

    binarypackage.cron.monthly -x3

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

    另请参见 dh_installcron(1) 和 cron(8)。

    binarypackage.cron.d -x3

    安装至 binarypackage 包内的 etc/cron.d/binarypackage 文件。

    参见 dh_installcron(1)、cron(8) 和 crontab(5)。

    binarypackage.default -x3

    若该文件存在,它将被安装至 binarypackage 包中的 etc/default/binarypackage 位置。

    参见 dh_installinit(1)。

    binarypackage.dirs -x1

    列出 binarypackage 包中要创建的目录。

    参见 dh_installdirs(1)。

    通常情况下您并不需要这么做,因为所有的 dh_install* 命令都会自动创建所需的目录。请仅在遇到问题时考虑使用这一工具。

    binarypackage.doc-base -x1

    作为 binarypackage 包中的 doc-base 控制文件进行安装。

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

    binarypackage.docs -x1

    列出要安装在 binarypackage 包中的文档文件。

    参见 dh_installdocs(1)。

    binarypackage.emacsen-compat -x3

    安装至 binarypackage 包中的 usr/lib/emacsen-common/packages/compat/binarypackage 文件。

    参见 dh_installemacsen(1)。

    binarypackage.emacsen-install -x3

    安装至 binarypackage 包中的 usr/lib/emacsen-common/packages/install/binarypackage 文件。

    参见 dh_installemacsen(1)。

    binarypackage.emacsen-remove -x3

    安装至 binarypackage 包中的 usr/lib/emacsen-common/packages/remove/binarypackage 文件。

    参见 dh_installemacsen(1)。

    binarypackage.emacsen-startup -x3

    安装至 binarypackage 包中的 usr/lib/emacsen-common/packages/startup/binarypackage 文件。

    参见 dh_installemacsen(1)。

    binarypackage.examples -x1

    列出要安装至 binarypackage 包中 usr/share/doc/binarypackage/examples/ 位置下的示例文件或目录。

    参见 dh_installexamples(1)。

    gbp.conf -x1

    如果该文件存在,它将作为 gbp 命令的配置文件发挥作用。

    参见 gbp.conf(5)、gbp(1) 和 git-buildpackage(1)。

    binarypackage.info -x1

    列出要安装至 binarypackage 包中的 info 文件。

    参见 dh_installinfo(1)。

    binarypackage.init -x4

    Installed into etc/init.d/binarypackage in binarypackage. (deprecated)

    参见 dh_installinit(1)。

    binarypackage.install -x1

    列出未被 dh_auto_install 命令安装的其它应当安装的文件。

    参见 dh_install(1) 和 dh_auto_install(1)。

    binarypackage.links -x1

    列出要生成符号链接的源文件和目标文件对。每一对链接均应在单独的一行中列出,源文件和目标文件之间使用空白字符分隔。

    参见 dh_link(1)。

    binarypackage.lintian-overrides -x3

    安装至软件包构建目录的 usr/share/lintian/overrides/binarypackage 位置。该文件用于消除 lintian 错误生成的诊断信息。

    参见 dh_lintian(1)、lintian(1) 和 Lintian 用户手册

    binarypackage.maintscript -x2

    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.

    manpage.* -x3

    这些文件是 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.

    binarypackage.manpages -x1

    列出要安装的 man 手册页。

    参见 dh_installman(1)。

    binarypackage.menu (已过时,不再安装)

    tech-ctte #741573 decided Debian should use .desktop files as appropriate.

    安装至 binarypackage 包中的 usr/share/menu/binarypackage Debian 菜单文件。

    参见 menufile(5) 以了解其格式。另请参见 dh_installmenu(1)。

    NEWS -x3

    安装至 usr/share/doc/binarypackage/NEWS.Debian 文件。

    参见 dh_installchangelogs(1)。

    patches/*

    这是 -p1 补丁文件的集合,它们将在使用源代码构建之前应用在上游源码上。

    debmake 默认不会生成补丁文件。

    参见 dpkg-source(1)、Section 4.4, “quilt setup”Section 5.9, “Step 3 (alternatives): Modification to the upstream source”

    patches/series -x1
    patches/* 补丁文件的应用顺序。
    binarypackage.preinst -x2, binarypackage.postinst -x2, binarypackage.prerm -x2, binarypackage.postrm -x2

    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.

    README.Debian -x1

    安装至 debian/control 文件列出的第一个二进制软件包中的 usr/share/doc/binarypackage/README.Debian 位置。

    该文件提供了针对该 Debian 软件包的信息。

    参见 dh_installdocs(1)。

    README.source -x1

    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.

    See Debian policy manual section 4.14.

    binarypackage.service -x3

    如果该文件存在,它将被安装到 binarypackage 包下面的 lib/systemd/system/binarypackage.service 位置。

    参见 dh_systemd_enable(1)、dh_systemd_start(1) 和 dh_installinit(1)。

    source/format -x1

    Debian 软件包格式。

    • 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 -x3

    These file is not installed, but are scanned by the lintian command to provide overrides for the source package.

    另请参考 dh_lintian(1) 和 lintian(1)。

    source/local-options -x1

    dpkg-source 命令使用此内容作为它的选项,比较重要的选项有:

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

    该文件不会包含在生成的源码包中,仅对维护者在版本控制系统中维护软件包有意义。

    See FILE FORMATS in dpkg-source(1).

    source/local-patch-header -x1

    自由格式的文本,将被包含在自动生成补丁的顶部。

    该文件不会包含在生成的源码包中,仅对维护者在版本控制系统中维护软件包有意义。

    See FILE FORMATS in dpkg-source(1).

    source/options -x3
    Use source/local-options instead to avoid issues with NMUs. See FILE FORMATS in dpkg-source(1).
    source/patch-header -x4
    Use source/local-patch-header instead to avoid issues with NMUs. See FILE FORMATS in dpkg-source(1).
    binarypackage.symbols -x1

    这些符号文件如果存在,将交由 dpkg-gensymbols 命令进行处理和安装。

    参见 dh_makeshlibs(1) 和 Section 9.16, “库符号”

    binarypackage.templates -x3
    这是 debconf 模板文件,用于在安装过程中向用户询问必需的问题以正确配置软件包。请参阅 Section 9.22, “debconf
    tests/control -x1
    This is the RFC822-style test meta data file defined in DEP-8. See autopkgtest(1) and Section 9.4, “持续集成”.
    TODO -x3

    安装至 debian/control 文件列出的第一个二进制包中的 usr/share/doc/binarypackage/TODO.Debian 文件。

    参见 dh_installdocs(1)。

    binarypackage.tmpfile -x3

    如果该文件存在,它将被安装至 binarypackage 包中的 usr/lib/tmpfiles.d/binarypackage.conf 文件。

    参见 dh_systemd_enable(1)、dh_systemd_start(1) 和 dh_installinit(1)。

    binarypackage.upstart -x4

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

    参见 dh_installinit(1)。

    upstream/metadata -x1
    Per-package machine-readable metadata about upstream (DEP-12). See Upstream MEtadata GAthered with YAml (UMEGAYA).


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