Chapter 7. 提示

Table of Contents

7.1. debdiff
7.2. dget
7.3. debc
7.4. piuparts
7.5. debsign
7.6. dput
7.7. bts
7.8. git-buildpackage
7.8.1. gbp import-dscs --debsnap
7.8.2. 上游 git 仓库
7.9. dgit
7.9.1. Snapshot upstream tarball (alternative git deborig approach)
7.10. chroot
7.11. 新的 Debian 版本
7.12. 新上游版本
7.12.1. uupdate + tarball
7.12.2. uscan
7.12.3. gbp
7.12.4. gbp + uscan
7.13. 3.0 源代码格式
7.14. CDBS
7.15. 在 UTF-8 环境下构建
7.16. UTF-8 转换
7.17. 上传 orig.tar.gz
7.18. 跳过的上传
7.19. 高级打包
7.20. 其他发行版
7.21. 除错

这里有一些关于 Debian 打包的值得注意的提示。

Debian now enforces the source-only upload when developing packages. So there may be 2 different *.changes files:

您可以使用 debdiff 命令来对比两个 Debian 软件包组成的差别。

$ debdiff old-package.dsc new-package.dsc

您也可以使用 debdiff 命令来对比两组二进制 Debian 软件包中的文件列表。

$ debdiff old-package.changes new-package.changes

当检查源代码包中哪些文件被修改时,这个命令非常有用。它还可以用来检测二进制包中是否有文件在更新过程中发生变动,比如被意外替换或删除。

您可以使用 dget 命令来下载 Debian 源包的文件集。

$ dget https://www.example.org/path/to/package_version-rev.dsc

您应该使用 debc 命令安装生成的软件包以在本地测试它。

$ debc package_version-rev_arch.changes

您应该使用 piuparts 命令安装生成的软件包以自动进行测试。

$ sudo piuparts package_version-rev_arch.changes
[Note] Note

这是一个非常慢的过程,因为它需要访问远程 APT 软件包仓库。

完成软件包的测试后,您可以使用 debsign 命令对其进行签名。

For uploading source-only package (normal):

$ debsign package_version-rev_source.changes

For uploading binary package:

$ debsign package_version-rev_arch.changes

使用 debsign 命令对包进行签名后,您可以使用 dput 命令上传 Debian 源和二进制包的文件集。

For uploading source-only package (normal):

$ dput package_version-rev_source.changes

For uploading binary package:

$ dput package_version-rev_arch.changes

上传软件包后,您将收到错误报告。 如《Debian 开发者参考》5.8. 处理缺陷 中所述,正确地管理这些错误是软件包维护者的一项重要职责。

bts 命令是一个用以处理 Debian 缺陷追踪系统 上的错误的便捷工具。

$ bts severity 123123 wishlist , tags -1 pending

git-buildpackage 软件包提供了许多命令来使用 git 仓库自动打包。

  • gbp import-dsc:向 git 仓库中导入先前的 Debian 源码包。
  • gbp import-orig:向 git 仓库中导入新的上游源码。

    • git import-orig 命令的 --pristine-tar 选项允许将上游源码包储存在同一个 git 仓库中。
    • --uscan 选项作为 gbp import-orig 命令的最后一个参数会允许下载上游原始码并提交到 git 仓库中。
  • gbp dch:从 git 提交信息中生成 Debian 变更信息(changelog)。
  • gbp buildpackage:从 git 仓库中构建 Debian 二进制包。

    • The sbuild package can be used as its clean chroot build backend either by configuration or adding --git-builder='sbuild -A -s --source-only-changes -v -d unstable'
  • gbp pull:从远程仓库中完全更新 debianupstreampristine-tar 分支。
  • gbp pqgit-dpmquilt(或者其别名 dquilt)命令用于管理兼容 quilt 的补丁。

    • dquilt 命令是学起来最简单的,它只要求您使用 git 命令手动提交最后的文件至 master 分支。
    • gbp pq” 命令提供了等效的补丁集管理功能,而不需要使用 dquilt 并且使用 git 的拣选(cherry-pick)功能简化了包含上游 git 仓库修改的操作流程。
    • git dpm” 命令提供了比 “gbp pq” 更强大的功能。

使用git-buildpackage软件包来管理软件包历史正成为绝大多数 Debian 维护者的实践标准。

参见:

[Tip] Tip

放松。您并不需要使用全部的打包工具,您只需要使用您所需要的那个就行。

对于记录在 snapshot.debian.org 归档中的名为 <source-package> 的 Debian 源码包,可以生成包含所有 Debian 版本历史的初始 git 存储库,如下所示。

$ gbp import-dscs --debsnap --pristine-tar '<source-package>'

The new dgit package offers commands to automate packaging activities using the git repository as an alternative to still popular gbp-buildpackage. Please read their guide:

  • dgit-maint-merge(7) — for dpkg-source "Format: 3.0 (quilt)" package with its changes flowing both ways between the upstream Git repository and the Debian Git repository which are tightly coupled.
  • dgit-maint-debrebase(7) — for dpkg-source "Format: 3.0 (quilt)" package with its changes flowing mostly one way from the upstream Git repository to the Debian Git repository.
  • dgit-maint-gbp(7) — for dpkg-source "Format: 3.0 (quilt)" package with its Debian Git repository which is kept usable also for people using gbp-buildpackage(1).
  • dgit-maint-native(7) — for dpkg-source "Format: 3.0 (native)" package in the Debian Git repository.

The dgit(1) command can push the easy-to-trace change history to the https://browse.dgit.debian.org/ site and can upload Debian package to the Debian repository properly without using dput(1).

  • dgit push-source — for uploading source-only package (normal)
  • dgit push — for uploading binary package

If you already use main and upstream branches in the Debian packaging repository (salsa.debian.org), you can use your local upstream-vcs-main branch to track the main branch of the upstream-vcs repository as:

 $ git fetch upstream-vcs main:upstream-vcs-main

Cherry picking bug fix commits from latest upstream commits are intuitive operation with dgit-maint-merge(7) and dgit-maint-debrebase(7). Just right-click those commits interactively on the upstream-vcs-main branch of the gitk(1) GUI dialog.

For quasi-native Debian binary package scheme situation described in Section 6.2, “Snapshot upstream tarball (-d, -t)” can be addressed using alternative git deborig approach adopting the dgit-maint-merge(7) scheme when debian/changelog contains the non-native version number with revision like 0.16-1.

 $ cd /path/to/upstream-git
 $ git rm -rf debian
 $ git tag -s upstream/0.16
 $ git reset --hard HEAD^
 $ git deborig
 $ sbuild

Here, for source format 3.0 (quilt), removal of files under debian/ directory in the upstream tarball is non-essential operation to quiet false positive warning from lintian.

For -1 revision, this use of git-deborig(1) as above is how this debmake-doc package generates the upstream tarball.

对于 -2, -3, … 修订版本号,你需要获取已经上传的上游 tarball 压缩包来代替。origtargz(1) 可以便利的做这个事情。

用于一个干净软件包构建环境的 chroot,可以使用 Chapter 3, 工具的配置 里描述的工具来创建和管理。[20]

以下是可用的软件包构建命令的快速总结。 有很多方法可以做同样的事情。

  • dpkg-buildpackage = 软件包打包工具的核心
  • debuild = dpkg-buildpackage + lintian (在清理后的环境变量下构建)
  • schroot = core of the Debian chroot environment tool
  • sbuild = schroot + dpkg-buildpackage (build in the chroot)
  • gbp = 在 git 下管理 Debian 源代码
  • gbp buildpackage = sbuild + dpkg-buildpackage + gbp (if configured with sbuild)

A clean unstable distribution chroot environment can be used as follows.

  • The chroot filesystem creation command for the unstable distribution

  • The master chroot filesystem path for the unstable distribution chroot filesystem

    • path: /srv/chroot/unstable-amd64-sbuild
  • The package build command for the unstable distribution chroot

    • sbuild
    • gbp buildpackage
  • The command to update the unstable chroot

    • sudo sbuild-update -udcar u
  • The command to login to the unstable chroot filesystem to modify it

    • sudo sbuild-shell u

Here, single "u" is predefined short alias for "unstable".

可以根据如下方式使用任意的 dist 版本环境。

  • 用于 dist 版本的 chroot 文件系统创建命令

  • dist 版本的 chroot 文件系统的文件路径

    • path: /srv/chroot/dist-amd64-sbuild
  • dist 版本 chroot 的包构建命令

    • sbuild -d dist
    • gbp buildpackage --git-dist=dist
  • 更新 dist chroot 的命令

    • sudo sbuild-update -udcar dist
  • The command to login to the master chroot (source:dist) of the dist distribution environment to modify it persistently

    • sudo sbuild-shell dist
[Tip] Tip

For building new experimental packages or for debugging buggy packages without using slow network access, this “sudo sbuild-shell dist” command can be used to pre-loaded some packages. Make sure to retain the backup of the original minimal chroot since changes are persistent and interfere with the normal test package building with the minimal chroot.

[Tip] Tip

If your old chroot filesystem is missing packages such as libeatmydata1, ccache, and lintian, you may want to install these with the “sudo sbuild-shell dist” command.

[Tip] Tip

When the orig.tar.gz file needs to be uploaded for a Debian revision other than 0 or 1 (e.g., for a security upload), add the -sa option to the end of dpkg-buildpackage, debuild, and sbuild commands. For the “gbp buildpackage” command, temporarily modify the builder setting of ~/.gbp.conf.

[Note] Note

本节中的描述过于简洁,对大多数潜在的维护者都没用。 这是作者的有意为之。 我们强烈建议您搜索并阅读与所用命令相关的所有文档。

[Note] Note

When an essential package becomes a non-essential one (e.g., adduser), you need to remove it manually from the existing chroot environment for its use by piuparts.

让我们假设有提交一个针对您的软件包的错误报告 #bug_number ,它描述了一个问题,您可以通过编辑上游源码中的 buggy 文件来解决。使用含有记录修复的 bugname.patch 文件,创建一个新的 Debian 修订版软件包,以下是所需的操作。

使用 dquilt 命令准备新的 Debian 软件包修订版本. 

 $ dquilt push -a
 $ dquilt new bugname.patch
 $ dquilt add buggy
 $ vim buggy
   ...
 $ dquilt refresh
 $ dquilt header -e
 $ dquilt pop -a
 $ dch -i

此外,如果软件包是用 git-buildpackage 命令以其默认配置管理的 git 仓库:

使用 gbp-pq 命令进行新的 Debian 修订. 

 $ git checkout master
 $ gbp pq import
 $ vim buggy
 $ git add buggy
 $ git commit
 $ git tag pq/<newrev>
 $ gbp pq export
 $ gbp pq drop
 $ git add debian/patches/*
 $ dch -i
 $ git commit -a -m "Closes: #<bug_number>"

请确保简明扼要地描述修复报告错误的更改并通过在 debian/changelog 文件中添加 “Closes: #<bug_number>” 来关闭这些错误。

[Tip] Tip

在实验时使用带有版本字符串的 debian/changelog 条目,例如 1.0.1-1~rc1 。然后,将这些更改日志条目整理到官方软件包的条目中。

如果 foo 包是以现代“3.0 (native)”或“3.0 (quilt)”格式正确打包的,则打包新的上游版本时需要将旧的 debian/ 目录移动到新的源码路径中。 这可以通过在新提取的源码路径中运行“tar -xvzf /path/to/foo_oldversion.debian.tar.gz”命令来完成。[21] 当然,你还需要做一些修改。

有很多的工具可以用以处理这些情况。在使用这些软件来更新上游版本后,请在 debian/changelog 文件中简要描述修复错误的上游修改,并添加 “Closes: #bug_number” 来关闭错误。

更新软件包的风格并不是更新软件包所必须的步骤。但是,这么做可以让您充分利用现代 debhelper3.0 源码格式的所有能力。

您应该核对一下 DEP——Debian 增强提议 并且采用已接受的提议。

参见 ProjectsDebSrc3.0 以核对 Debian 工具链对新 Debian 源码格式的支持情况。

Common Debian Build System (CDBS)是 debhelper 软件包的包装系统。CDBS 基于 Makefile 包含机制并且由 debian/rules 文件中设置的 DEB_* 变量配置。

在将 dh 命令引入第七版的 debhelper 软件包之前,CDBS 是创建简单干净的 debian/rules 文件的唯一方法。

对于很多简单的软件包,现在 dh 命令使 debian/rules 文件很简洁,建议保持构建系统简洁,而非使用冗长的 CDBS

[Note] Note

CDBS 神奇地让我用更少的命令来完成工作”和“我不懂新的 dh 的语法”都不是您继续使用旧的 CDBS 系统的借口。

对于一些复杂的软件包,比如与 GNOME 相关的,当前的维护者有理由利用 CDBS 自动化完成他们的统一包装。如果是这种情况,请不要费心从 CDBS 转换为 dh 语法。

[Note] Note

如果您正在与维护 团队 合作,请遵循团队的既定惯例。

将软件包从 CDBS 转换为 dh 语法时,请使用以下内容作为参考:

构建环境的默认语言环境是 C

某些程序(如 Python3 的 read 函数)会根据区域设置改变行为。

添加以下代码到 debian/rules 文件可以确保程序使用 C.UTF-8 的区域语言设置(locale)进行构建。

LC_ALL := C.UTF-8
export LC_ALL

如果上游文档是用旧编码方案编码的,那么将它们转换为 UTF-8 是个好主意。

请使用 libc-bin 包中的 iconv 命令来转换纯文本文件的编码。

 $ iconv -f latin1 -t utf8 foo_in.txt > foo_out.txt

使用 w3m(1) 将 HTML 文件转换为 UTF-8 纯文本文件。 执行此操作时,请确保在 UTF-8 语言环境下执行它。

 $ LC_ALL=C.UTF-8 w3m -o display_charset=UTF-8 \
        -cols 70 -dump -no-graph -T text/html \
        < foo_in.html > foo_out.txt

debian/rules 文件的 override_dh_* 目标中运行这些脚本。

当您第一次向归档上传软件包时,您还需要包含原始的 orig.tar.gz 源码。

如果 Debian 修订码是 1 或者 0,这都是默认的。否则,您必须使用带有 -sa 选项的 dpkg-buildpackage 命令。

  • dpkg-buildpackage -sa
  • debuild -sa
  • *sbuild
  • 对于 gbp buildpackage,请编辑 ~/.gbp.conf 文件。
[Tip] Tip

另一方面,-sd 选项将会强制排除原始的 orig.tar.gz 源码。

[Tip] Tip

添加至 ~/.bashrc 文件。

如果当跳过上传时,你在 debian/changelog 中创建了多个条目,你必须创建一个包含自上次上传以来所有变更的 debian/changelog 文件。这可以通过指定 dpkg-buildpackage 选项 -v 以及上次上传的版本号,比如 1.2 来完成。

  • dpkg-buildpackage -v1.2
  • debuild -v1.2
  • sbuild --debbuildopts -v1.2
  • 对于 gbp buildpackage,请编辑 ~/.gbp.conf 文件。

关于以下内容的提示可以在 debhelper(7) 手册页中找到:

关于以下内容的提示可以在 dpkg-source(1) 手册页中找到:

  • 多个上游源码包的命名约定

    • 软件包名_版本.orig.tar.gz
    • 软件包名_版本.orig-部件名.tar.gz
  • 将 Debian 更改记录到上游源码包中

    • dpkg-source --commit

尽管上游的原始码有着所有构建 Debian 软件包所需的信息,找出使用何种选项的组合仍然不是一件简单的事。

此外,上游的包可能更专注于功能的增强,而并不那么重视向后兼容性等特性,这是 Debian 打包实践中的一个重要方面。

利用其他发行版的信息是解决上述问题的一种选择。

如果其他发行版是由 Debian 派生的,重新使用它是没有价值的。

如果其他发行版是基于 RPM 的发行版,请参见 Repackage src.rpm

通过 rget 命令,可以下载并打开 src.rpm文件。(请将 rget 脚本添加至 PATH 中)

rget 脚本. 

#!/bin/sh
FCSRPM=$(basename $1)
mkdir ${FCSRPM}; cd ${FCSRPM}/
wget $1
rpm2cpio ${FCSRPM} | cpio -dium

许多上游源码包包含 RPM 系统使用的、以 packagename.spec 或者 packagename.spec.in 命名的SPEC 文件。这可以被用做 Debian 软件包的基点。

当您遇到构建问题或者生成的二进制程序核心转储时,您需要自行解决他们。这就是除错(debug)

This is too deep a topic to describe here. So, let me just list few pointers and hints for some typical debug tools.

  • 核心转储

    • man core
    • 更新 “/etc/security/limits.conf” 文件来包含以下代码:

      * soft core unlimited
    • ~/.bashrc 中添加“ulimit -c unlimited
    • 使用 “ulimit -a” 来检查
    • 按下 Ctrl-\ 或者“kill -ABRT PID” 来建立一个核心转储文件
  • gdb - The GNU Debugger

    • info gdb
    • 参见 /usr/share/doc/gdb-doc/html/gdb/index.html 中的 “Debugging with GDB”
  • strace - 跟踪系统调用和信号

    • 使用 /usr/share/doc/strace/examples/ 中的 strace-graph 脚本来建立一个好看的树形图
    • man strace
  • ltrace - 跟踪库调用

    • man ltrace
  • sh -n script.sh” - Shell 脚本的语法检查
  • sh -x script.sh” - 跟踪 Shell 脚本
  • python -m py_compile script.py” - Python 脚本的语法检查
  • python -mtrace --trace script.py” - 跟踪 Python 脚本
  • perl -I ../libpath -c script.pl” - Perl 脚本的语法检查
  • perl -d:Trace script.pl” - 跟踪 Perl 脚本

    • 安装 libterm-readline-gnu-perl 软件包或者同类型软件来添加输入行编辑功能与历史记录支持。
  • lsof - 按进程列出打开的文件

    • man lsof
[Tip] Tip

script 命令能帮助记录控制台输出。

[Tip] Tip

ssh 命令中搭配使用 screentmux 命令,能够提供安全并且强健的远程连接终端。

[Tip] Tip

libreply-perl(新的)软件包和来自 libdevel-repl-perl(旧的)软件包的 re.pl 命令为 Perl 提供了一个类似 Python 和 Shell 的 REPL (=READ + EVAL + PRINT + LOOP) 环境。

[Tip] Tip

rlwraprlfe 命令为所有交互命令提供了输入行编辑功能。例如 “rlwrap dash -i”。



[20] The sbuild style chroot organization is deployed here. See https://wiki.debian.org/sbuild . Be careful since many HOWTOs use different chroot setups.

[21] 如果 foo 包是以旧的 1.0 格式打包的,则相对的,只要在新的源代码路径中执行“zcat /path/to/foo_oldversion.diff.gz|patch -p1”命令。

[22] 您可以使用 splitdiff 命令来将 big.diff 文件分割成多个小的增量更新补丁文件。