第 4 章 工具的配置

# 第 4 章 工具的配置

build-essential 软件包必须在构建环境内预先安装。

The devscripts package should be installed in the development environment of the maintainer.

It is a good idea to install and set up all of the popular set of packages mentioned in this chapter. These enable us to share the common baseline working environment, although these are not necessarily absolute requirements.

Please also consider to install the tools mentioned in the “Overview of Debian Maintainer Tools” in the “Debian Developer’s Reference”, as needed.

| 小心
这里展示的工具配置方式仅作为示例提供，可能与系统上最新的软件包相比有所落后。Debian 的开发具有一个移动的目标。请确保阅读合适的文档并按照需要更新配置内容。

## 4.1. Email setup

许多 Debian 维护工具识别并使用 shell 环境变量 $DEBEMAIL 和 $DEBFULLNAME 作为作为您的电子邮件地址和名称。

Let’s set these environment variables by adding the following lines to \~/.bashrc [6].

添加至 ~/.bashrc 文件.

    DEBEMAIL="osamu@debian.org"
    DEBFULLNAME="Osamu Aoki"
    export DEBEMAIL DEBFULLNAME

| 注意
上面的例子使用了本指南作者的个人信息作为示例。本指南展示的配置和操作实例都将使用这里的电子邮件地址和名称设置。在您的系统上，您必须使用您自己的电子邮件地址和姓名。

## 4.2. mc 设置

mc 命令提供了管理文件的简单途径。它可以打开二进制 deb 文件，并仅需对二进制 deb 文件按下回车键便能检查其内容。它调用了 dpkg-deb 命令作为其后端。我们可以按照下列方式对其配置，以支持简易 chdir 操作。

添加至 ~/.bashrc 文件.

    # mc related
    if [ -f /usr/lib/mc/mc.sh ]; then
      . /usr/lib/mc/mc.sh
    fi

## 4.3. git 设置

如今 git 命令已成为管理带历史的源码树的必要工具。

git 命令的用户级全局配置，如您的名字和电子邮件地址，保存在 ~/.gitconfig 文件中，且可以使用如下方式配置。

    [~] $ git config --global user.name "Osamu Aoki"
    [~] $ git config --global user.email osamu@debian.org

如果您仍然只习惯 CVS 或者 Subversion 的命令风格，您可以使用如下方式设置几个命令别名。

    [~] $ git config --global alias.ci "commit -a"
    [~] $ git config --global alias.co checkout

您可以使用如下命令检查全局配置。

    [~] $ git config --global --list

| 提示
有必要使用某些图形界面 git 工具，例如 gitk 或 gitg 命令来有效地处理 git 仓库的历史。

## 4.4. quilt 设置

quilt 命令提供了记录修改的一个基本方式。对 Debian 打包来说，该工具需要进行自定义，从而在 debian/patches/ 目录内记录修改内容，而非使用默认的 patches/ 目录。

为了避免改变 quilt 命令自身的行为，我们在这里创建一个用于 Debian 打包工作的命令别名：dquilt。之后，我们将对应内容写入 ~/.bashrc 文件。下面给出的第二行为 dquilt 命令提供与 quilt 命令相同的命令行补全功能。

添加至 ~/.bashrc 文件.

    alias dquilt="quilt --quiltrc=${HOME}/.quiltrc-dpkg"
    . /usr/share/bash-completion/completions/quilt
    complete -F _quilt_completion $_quilt_complete_opt dquilt

然后我们来创建具有如下内容的 ~/.quiltrc-dpkg 文件。

    d=.
    while [ ! -d $d/debian -a `readlink -e $d` != / ];
        do d=$d/..; done
    if [ -d $d/debian ] && [ -z $QUILT_PATCHES ]; then
        # if in Debian packaging tree with unset $QUILT_PATCHES
        QUILT_PATCHES="debian/patches"
        QUILT_PATCH_OPTS="--reject-format=unified"
        QUILT_DIFF_ARGS="-p ab --no-timestamps --no-index --color=auto"
        QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index"
        QUILT_COLORS="diff_hdr=1;32:diff_add=1;34:diff_rem=1;31:diff_hunk=1;33:"
        QUILT_COLORS="${QUILT_COLORS}diff_ctx=35:diff_cctx=33"
        if ! [ -d $d/debian/patches ]; then mkdir $d/debian/patches; fi
    fi

See quilt(1) and “How To Survive With Many Patches or Introduction to Quilt (quilt.html)” on how to use the quilt command.

要获取使用示例，请查看 “第 5.9 节 “Step 3 (alternatives): Modification to the upstream source””。

Note that “gbp pq” is able to consume existing debian/patches, automate updating and modifying the patches, and export them back into debian/patches, all without using quilt nor the need to learn or configure quilt.

## 4.5. openPGP setup

The gpg(1) command, included in the gnupg package, can be used to generate a new openPGP key for the Debian package activity as follows.

    [~] $ gpg --generate-key
    gpg (GnuPG) 2.4.7; Copyright (C) 2024 g10 Code GmbH
    ... [snip] ...
    public and secret key created and signed.

    pub   ed25519 2026-02-10 [SC] [expires: 2029-02-09]
          ABCDEF0123456789ABCDEF0123456789ABCDEF01
    uid                      Osamu Aoki  <osamu@debian.org>
    sub   cv25519 2026-02-10 [E] [expires: 2029-02-09]

This is an openPGP key based on the Elliptic-curve cryptography (ECC).

| 注意
If you already have an openPGP key based on the RSA cryptosystem signed by many others, you can use it.

You can edit and update this openPGP key with:

    [~] $ gpg --edit-key ABCDEF0123456789ABCDEF0123456789ABCDEF01
    ... [snip] ...
    gpg> save

For example, the resulting openPGP key may look like:

    [~] $ gpg --list-keys ABCDEF0123456789ABCDEF0123456789ABCDEF01
    pub   ed25519 2026-02-10 [SC]
          ABCDEF0123456789ABCDEF0123456789ABCDEF01
    uid           [ultimate] Osamu Aoki <osamu@debian.org>
    sub   cv25519 2026-02-10 [E] [expires: 2030-02-10]

| 注意
The term “GPG key” found in many Debian documents can be considered as a synonym of “openPGP key”.

For more on OpenPGP key, see:

- “Creating a new GPG key”
- “Debian wiki: Keysigning”
- “Debian wiki: Using OpenPGP subkeys in Debian development”
- “Debian wiki: FixKeyWithSha1”— updating old OpenPGP keys

## 4.6. devscripts 设置

The debsign command, included in the devscripts package, is used to sign the Debian package with your private openPGP key.

debuild 命令同样由 devscripts 软件包提供，它可以构建二进制软件包并使用 lintian 命令对其进行检查。lintian 命令的详细输出通常都很实用。

您可以将下列内容写入 ~/.devscripts 文件来进行配置。

    DEBUILD_DPKG_BUILDPACKAGE_OPTS="-i -I -us -uc"
    DEBUILD_LINTIAN_OPTS="-i -I --show-overrides"
    DEBSIGN_KEYID="Your_openPGP_keyID"

The -i and -I options in DEBUILD_DPKG_BUILDPACKAGE_OPTS for the dpkg-source command help rebuilding of Debian packages without extraneous contents (see “第 8 章 Sanitization of the source”).

## 4.7. sbuild 设置

The sbuild package provides a clean room (“chroot”) build environment. It offers this efficiently with the help of schroot using the bind-mount feature of the modern Linux kernel.

Since it is the same build environment as the Debian’s buildd infrastructure, it is always up to date and comes full of useful features.

It can be customized to offer following features:

- The schroot package to boost the chroot creation speed.
- lintian 软件包能找到所构建软件包中的缺陷。
- The piuparts package to find bugs in the package.
- The autopkgtest package to find bugs in the package.
- ccache 软件包可以加速 gcc。（可选）
- libeatmydata1 软件包可以加速 dpkg。（可选）
- 并行运行 make 以提高构建速度。（可选）

Let’s set up sbuild environment [7]:

    [~] $ sudo apt install sbuild piuparts autopkgtest lintian
    [~] $ sudo apt install sbuild-debian-developer-setup
    [~] $ sudo sbuild-debian-developer-setup -s unstable

Let’s update your group membership to include sbuild and verify it:

    [~] $ newgrp -
    [~] $ id
    uid=1000(<yourname>) gid=1000(<yourname>) groups=...,132(sbuild)

Here, “reboot of system” or “kill -TERM -1” can be used instead to update your group membership [8] .

Let’s create the configuration file ~/.local/sbuild/config.pl in line with recent Debian practice of “source-only-upload” as:

    [~] $ cat >~/.local/sbuild/config.pl << 'EOF'
    ##############################################################################
    # PACKAGE BUILD RELATED (source-only-upload as default)
    ##############################################################################
    # -d
    $distribution = 'unstable';
    # -A
    $build_arch_all = 1;
    # -s
    $build_source = 1;
    # --source-only-changes
    $source_only_changes = 1;
    # -v
    $verbose = 1;

    ##############################################################################
    # POST-BUILD RELATED (turn off functionality by setting variables to 0)
    ##############################################################################
    $run_lintian = 1;
    $lintian_opts = ['-i', '-I'];
    $run_piuparts = 1;
    $piuparts_opts = ['--schroot', 'unstable-amd64-sbuild'];
    $run_autopkgtest = 1;
    $autopkgtest_root_args = '';
    $autopkgtest_opts = [ '--', 'schroot', '%r-%a-sbuild' ];

    ##############################################################################
    # PERL MAGIC
    ##############################################################################
    1;
    EOF

| 注意
There are some exceptional cases such as NEW uploads, uploads with NEW binary packages, and security uploads where you can’t do source-only-upload but are required to upload with binary packages. The above configuration needs to be adjusted for those exceptional cases.

| 提示
You may need to add “$chroot_mode = "schroot";” to ~/.local/sbuild/config.pl for piuparts if it doesn’t work well under unshare. See Debian bug: #1125784 and #1126127.

Following document assumes that sbuild is configured this way.

Edit this to your needs. Post-build tests can be turned on and off by assigning 1 or 0 to the corresponding variables,

| 警告
可选的自定义项可能造成负面影响。如果有疑问，请禁用它们。

| 注意
并行的 make 可能在某些已有软件包上运行失败，它同样会使得构建日志难以阅读。

| 提示
Many sbuild related hints are available at “第 9.7 节 “Note on sbuild”” and “https://wiki.debian.org/sbuild” .

## 4.8. Persistent chroot setup

| 注意
Use of independent copied chroot filesystem prevents contaminating the source chroot used by sbuild.

For building new experimental packages or for debugging buggy packages, let’s setup dedicated persistent chroot “source:unstable-amd64-desktop” by:

    [~] $ sudo cp -a /srv/chroot/unstable-amd64-sbuild /srv/chroot/unstable-amd64-desktop
    [~] $ sudo tee /etc/schroot/chroot.d/unstable-amd64-desktop-XXXXXX << EOF
    [unstable-amd64-desktop]
    description=Debian sid/amd64 persistent chroot
    groups=root,sbuild
    root-groups=root,sbuild
    profile=desktop
    type=directory
    directory=/srv/chroot/unstable-amd64-desktop
    union-type=overlay
    EOF

Here, desktop profile is used instead of sbuild profile. Please make sure to adjust /etc/schroot/desktop/fstab to make package source accessible from inside of the chroot.

You can log into this chroot “source:unstable-amd64-desktop” by:

    [~] $ sudo schroot -c source:unstable-amd64-desktop

## 4.9. gbp 设置

The git-buildpackage package offers the gbp(1) command. Its user configuration file is ~/.gbp.conf.

    # Configuration file for "gbp <command>"

    [DEFAULT]
    # the default build command:
    builder = sbuild
    # use pristine-tar:
    pristine-tar = True
    # Use color when on a terminal, alternatives: on/true, off/false or auto
    color = auto

## 4.10. HTTP 代理

您应当在本地设置 HTTP 缓存代理以节约访问 Debian 软件仓库的带宽。可以考虑以下几种选项：

- 特化的 HTTP 缓存代理，使用 apt-cacher-ng 软件包。
- Generic HTTP caching proxy (squid package) configured by squid-deb-proxy package

In order to use this HTTP proxy without manual configuration adjustment, it’s a good idea to install either auto-apt-proxy or squid-deb-proxy-client package to everywhere.

## 4.11. 私有 Debian 仓库

您可以使用 reprepro 软件包搭建私有 Debian 仓库。

## 4.12. 虚拟机

For testing GUI application, it is a good idea to have virtual machines. Install virt-manager and qemu-kvm packages.

Use of chroot and virtual machines allows us not to update the whole host PC to the latest unstable suite.

## 4.13. 本地网络中的虚拟机

如需经由本地网络轻松访问虚拟机，可以考虑安装 avahi-utils 来设置 DNS 多播服务的自动发现基础设施。

对所有运行中的虚拟机以及主机，我们可以使用各自的主机名加上后缀的 .local 来使用 SSH 互相访问。

[6] This assumes you are using Bash as your login shell. If you use some other login shell such as Z shell, use their corresponding configuration files instead of \~/.bashrc.

[7] Be careful since some older HOWTOs may use different chroot setups.

[8] Simply “logout and login under some modern GUI Desktop environment” may not update your group membership.

第 3 章 预备知识 |  | 第 5 章 简单打包