章 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

| 注意
The above is for the author of this manual. The configuration and operation examples presented in this manual use these email address and name settings. You must use your email address and name for your system.

## 4.2. mc setup

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 setup

如今 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 setup

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 setup

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 setup

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 setup

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. Virtual machines

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. Local network with virtual machines

In order to access virtual machines easily over the local network, setting up multicast DNS service discovery infrastructure by installing avahi-utils is a good idea.

For all running virtual machines and the host PC, we can use each host name appended with .local for SSH to access each other.

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