Debian 打包完整流程参考

Yoimiya2026/6/13大约 4 分钟

参考

一、工具与角色速览

Debian 打包的核心工具链：

工具	作用
`debmake` / `dh_make`	生成初始 `debian/` 骨架
`dch`	维护 `debian/changelog`
`uscan`	根据 `debian/watch` 找 upstream 新版
`gbp import-orig`	把 upstream tarball 导入 Git
`quilt`	维护 `debian/patches/`
`gbp buildpackage`	从 Git 工作树发起构建
`sbuild`	在干净 chroot 里真正构建
`lintian` / `autopkgtest` / `piuparts`	构建后的质量检查

upstream 管源码来源 → git + gbp 管版本流转 → dch + quilt 管 Debian delta → sbuild 管干净构建 → lintian 管验收。

二、环境准备

基础工具

sudo apt install \
  autopkgtest \
  build-essential \
  ca-certificates \
  debian-archive-keyring \
  devscripts \
  git \
  git-buildpackage \
  lintian \
  mmdebstrap \
  piuparts \
  pristine-tar \
  quilt \
  sbuild \
  uidmap

如需 GPG 签名上传：

sudo apt install gnupg gpg-agent

身份信息

# ~/.bashrc
DEBEMAIL="[email protected]"
DEBFULLNAME="Rukkhadevata123"
export DEBEMAIL DEBFULLNAME

# ~/.gitconfig
[user]
    email = [email protected]
    name = Rukkhadevata123

OpenPGP key（可选，用于签名 tag / upload）

gpg --full-generate-key
gpg --list-secret-keys --keyid-format LONG

三、gbp 配置与仓库模型

~/.gbp.conf：

[DEFAULT]
pristine-tar = True
pristine-tar-commit = True
upstream-branch = upstream/latest
debian-branch = debian/latest
builder = sbuild --no-clean-source

# 如需自动签名 tag：
# sign-tags = True
# keyid = <fingerprint>

upstream 源码在 upstream/latest
Debian 打包在 debian/latest
维护 pristine-tar，确保可复现 orig tarball
构建走 sbuild

从 Salsa clone 后补本地分支

Salsa 克隆后本地可能只有当前分支，gbp import-orig --uscan 会报 Repository does not have branch 'upstream/latest'。补上即可：

git fetch origin
git branch --track upstream/latest origin/upstream/latest
git branch --track pristine-tar origin/pristine-tar
git switch debian/latest
gbp import-orig --uscan

四、导入 upstream

从 tarball 新建

mkdir foo && cd foo && git init
gbp import-orig ../foo-1.2.3.tar.gz

gbp 会自动创建 upstream/latest、debian/latest 分支并维护 pristine-tar。

用 uscan + watch 更新

前提：debian/watch 已写好。

uscan --verbose                     # 检查是否有新版
uscan --verbose --download-current-version
gbp import-orig --uscan             # 导入
gbp import-orig --uscan --upstream-version 1.2.3

从 dsc 导入（接手已有包）

gbp import-dsc ../foo_1.2.3-1.dsc

五、维护 Debian delta

dch

dch -i                              # 增加 Debian revision
dch -v 1.2.3-1                      # 指定新版本
dch -r                              # UNRELEASED → 发布
dch -l +local "Local test build"    # 本地测试构建

quilt

quilt new fix-build.patch
quilt edit src/foo.c
quilt diff
quilt refresh

quilt push -a   # 应用全部 patch
quilt pop -a    # 取消全部 patch
quilt series    # 查看 patch 列表

建议：一个 patch 只做一件事，命名写清楚。

debian/source/format

3.0 (quilt)

这是当前标准格式，upstream 源码在 orig.tar.*，Debian 改动在 debian/patches/。

debian/source/options（single-debian-patch）

single-debian-patch

作用：工作树里的改动自动合并为一个 Debian patch，不用手动 quilt。

适合：私有小包、delta 很小、不想拆 patch
不适合：长期维护、patch 多、需要 upstream 回溯

简单说：省事用 single-debian-patch，长期维护用显式 quilt patch。

六、构建

sbuild 配置

~/.config/sbuild/config.pl（完整注释见 Debian Wiki）：

$enable_network = 1;
$chroot_mode = 'unshare';
$external_commands = { "build-failed-commands" => [ [ '%SBUILD_SHELL' ] ] };

$build_arch_all = 1;
$build_source = 1;
$source_only_changes = 1;

$run_lintian = 1;
$lintian_opts = ['--display-info', '--verbose', '--fail-on', 'error,warning', '--info'];

$run_autopkgtest = 1;
$run_piuparts = 1;
$piuparts_opts = ['--no-eatmydata', '--distribution=%r', '--fake-essential-packages=systemd-sysv'];

创建构建环境：

mkdir -p ~/.cache/sbuild
mmdebstrap --include=ca-certificates --skip=output/dev --variant=buildd \
  unstable ~/.cache/sbuild/unstable-amd64.tar.zst \
  https://deb.debian.org/debian

gbp buildpackage

~/.gbp.conf 已配 builder = sbuild --no-clean-source，所以：

gbp buildpackage                                         # 标准构建
gbp buildpackage --git-ignore-new                        # 忽略本地未提交改动
gbp buildpackage --git-ignore-branch                     # 忽略分支检查
gbp buildpackage --git-tag                               # 构建后自动打 tag

日常节奏：

# 调试
gbp buildpackage --git-ignore-new --git-ignore-branch

# 正式
git add debian/ && git commit -m "debian: refresh packaging"
gbp buildpackage --git-tag

七、验证

构建成功后还需要检查质量：

lintian ../foo_*.changes                    # 打包规范检查
autopkgtest --null-directory ../foo_*.dsc   # 安装后功能测试
sudo piuparts ../foo_*.deb                  # 安装/升级/卸载流程检查

如果 sbuild 配置中已启用 $run_lintian、$run_autopkgtest、$run_piuparts，构建时会自动执行。

八、debian/ 目录文件速查

文件	用途
`control`	源包和二进制包元数据（依赖、描述等）
`copyright`	DEP-5 格式版权信息
`changelog`	版本历史，用 `dch` 维护
`rules`	构建入口，最小 `#!/usr/bin/make -f` + `dh $@`
`watch`	告诉 uscan 去哪找 upstream 新版
`upstream/metadata`	upstream 仓库、bug tracker 等元信息
`source/format`	写 `3.0 (quilt)`
`source/options`	写 `single-debian-patch`（可选）
`patches/*` + `patches/series`	对上游源码的 patch
`foo.install`	描述哪些文件装进哪个二进制包

九、工作流速查

新包

git init && gbp import-orig ../foo-1.2.3.tar.gz
# 补 debian/ 文件
quilt new fix-build.patch && quilt edit src/foo.c && quilt refresh
dch -v 1.2.3-1 "Initial Debian release"
gbp buildpackage

更新 upstream

uscan --verbose
gbp import-orig --uscan
dch -v 1.2.4-1 "New upstream release"
quilt push -a && quilt refresh
gbp buildpackage

只修 Debian 打包

dch -i "Adjust Build-Depends and install paths"
gbp buildpackage

十、总结

Debian 打包的核心：

上游源码 — 从哪来、怎么跟踪版本
Debian delta — 放 debian/patches 还是 single-debian-patch
版本管理 — dch 管 changelog，uscan + watch 管上游
Git 工作流 — gbp 管导入和构建
质量验收 — sbuild 干净构建 + lintian / piuparts 检查