章 5. Simple packaging

這裡給出了從簡單的 C 語言原始碼建立簡單的 Debian 套件的例子，並假設上游使用了 Makefile 作為構建系統。

Let’s assume this upstream tarball to be debhello-0.0.tar.xz.

這一類原始碼設計可以用這樣的方式安裝成為非系統檔案：

Basics for the install from the upstream tarball. 

[base_dir] $ tar --xz -xmf debhello-0.0.tar.xz
[base_dir] $ cd debhello-0.0
[debhello-0.0] $ make
[debhello-0.0] $ make install

Debian packaging requires changing this “make install” process to install files to the target system image location instead of the normal location under /usr/local.

	注意
	在其它更加複雜的構建系統下構建 Debian 套件的例子可以在 “章 14, 更多範例” 找到。

The big picture for building a single non-native Debian package from the upstream tarball debhello-0.0.tar.xz can be summarized as:

套件構建的大致流程. 

[base_dir] $ tar --xz -xmf debhello-0.0.tar.xz
[base_dir] $ cd debhello-0.0
[debhello-0.0] $ debmake
I: debmake (version: 5.1.4)
I: Copyright © 2014-2026 Osamu Aoki <osamu@debian.org>
   ...
[debhello-0.0] $ ... manual customization of debian/* files
[debhello-0.0] $ debuild
   ...

	提示
	The debuild command in this and following examples may be substituted by equivalent commands such as the sbuild command.

	提示
	If the upstream tarball in the .tar.xz format is available, use it instead of the one in the .tar.xz and .tar.bz2 formats. The xz compression format offers the better compression than the gzip and bzip2 compressions.

這裡給出與 debuild 命令類似的一系列命令的一個彙總。

我們先要取得上游原始碼。

Download debhello-0.0.tar.xz. 

[base_dir] $ wget http://www.example.org/download/debhello-0.0.tar.xz
 ...
[base_dir] $ tar --xz -xmf debhello-0.0.tar.xz
[base_dir] $ tree
.
├── debhello-0.0
│   ├── Makefile
│   ├── README.md
│   └── src
│       └── hello.c
└── debhello-0.0.tar.xz

3 directories, 4 files

這裡的 C 原始碼 hello.c 非常的簡單。

hello.c. 

[base_dir] $ cat debhello-0.0/src/hello.c
#include <stdio.h>
int
main()
{
        printf("Hello, world!\n");
        return 0;
}

debmake 命令的輸出十分詳細，如下所示，它可以展示程式的具體操作內容。

The output from the debmake command with -x1 option. 

[base_dir] $ cd debhello-0.0
[debhello-0.0] $ debmake -x1
I: debmake (version: 5.1.4)
I: Copyright © 2014-2026 Osamu Aoki <osamu@debian.org>
I: [debhello-0.0] $ cd ..
I: Non-native Debian package pkg="debhello", ver="0.0", rev="1" method="dir_d...
I: already in the package-version form: "debhello-0.0"
I: [base_dir] $ ln -sf debhello-0.0.tar.xz debhello_0.0.orig.tar.xz
I: [base_dir] $ cd debhello-0.0
I: parsing option -b ""
I: binary package=debhello Type=bin / Arch=any M-A=foreign
I: build_type = make
I: ext_type = c                       1 files
I: ext_type = md                      1 files
I: creating debian/* files with "-x 1" option
I: [debhello-0.0] $ licensecheck --recursive --copyright --deb-machine  . > d...
I: creating debian/copyright by licensecheck.
I: creating debian/control from control.py
I: creating debian/control by control.py
I: creating debian/changelog from extra0_changelog
I: creating debian/rules from extra0_rules
I: creating debian/source/format from extra0source_format
I: creating debian/README.Debian from extra1_README.Debian
I: creating debian/README.source from extra1_README.source
I: creating debian/clean from extra1_clean
I: creating debian/dirs from extra1_dirs
I: creating debian/docs from extra1_docs
I: creating debian/examples from extra1_examples
I: creating debian/gbp.conf from extra1_gbp.conf
I: creating debian/links from extra1_links
I: creating debian/manpages from extra1_manpages
I: creating debian/salsa-ci.yml from extra1_salsa-ci.yml
I: creating debian/watch from extra1nn_watch
I: creating debian/tests/control from extra1tests_control
I: creating debian/upstream/metadata from extra1upstream_metadata
I: creating debian/patches/series from extra1patches_series
I: creating debian/install from extra1bin_install
I: [debhello-0.0] $ wrap-and-sort -ast
I: debian/* may have a blank line at the top.

debmake 命令基於命令列選項產生所有這些模板檔案。如果沒有指定具體選項，debmake 命令將為您自動選擇合理的預設值：

	注意
	Here, the debmake command is invoked with the -x1 option to keep this tutorial simple. Use of default -x2 or more extensive -x3 option is highly recommended.

我們來檢查一下自動產生的模板檔案。

基本 debmake 命令執行後的原始碼樹。. 

[debhello-0.0] $ cd ..
[base_dir] $ tree
.
├── debhello-0.0
│   ├── Makefile
│   ├── README.md
│   ├── debian
│   │   ├── README.Debian
│   │   ├── README.source
│   │   ├── changelog
│   │   ├── clean
│   │   ├── control
│   │   ├── copyright
│   │   ├── dirs
│   │   ├── docs
│   │   ├── examples
│   │   ├── gbp.conf
│   │   ├── install
│   │   ├── links
│   │   ├── manpages
│   │   ├── patches
│   │   │   └── series
│   │   ├── rules
│   │   ├── salsa-ci.yml
│   │   ├── source
│   │   │   └── format
│   │   ├── tests
│   │   │   └── control
│   │   ├── upstream
│   │   │   └── metadata
│   │   └── watch
│   └── src
│       └── hello.c
├── debhello-0.0.tar.xz
└── debhello_0.0.orig.tar.xz -> debhello-0.0.tar.xz

8 directories, 25 files

這裡的 debian/rules 檔案是應當由套件維護者提供的構建指令碼。此時該檔案是由 debmake 命令產生的模板檔案。

debian/rules（模板檔案）：. 

[base_dir] $ cd debhello-0.0
[debhello-0.0] $ cat debian/rules
#!/usr/bin/make -f
# You must remove unused comment lines for the released package.
# See debhelper(7) (un-comment to enable)
# This is an autogenerated template for debian/rules.
#
# Output every command that modifies files on the build system.
#export DH_VERBOSE = 1
#
# Copy some variable definitions from pkg-info.mk and vendor.mk
# under /usr/share/dpkg/ to here if they are useful.
#
# See FEATURE AREAS/ENVIRONMENT in dpkg-buildflags(1)
# Apply all hardening options
#export DEB_BUILD_MAINT_OPTIONS = hardening=+all
# Package maintainers to append CFLAGS
#export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
# Package maintainers to append LDFLAGS
#export DEB_LDFLAGS_MAINT_APPEND = -Wl,-O1
#
# With debhelper version 9 or newer, the dh command exports
# all buildflags.  So there is no need to include the
# /usr/share/dpkg/buildflags.mk file here if compat is 9 or newer.
#
# These are rarely used code. (START)
#
# The following include for *.mk magically sets miscellaneous
# variables while honoring existing values of pertinent
# environment variables:
#
# Architecture-related variables such as DEB_TARGET_MULTIARCH:
#include /usr/share/dpkg/architecture.mk
# Vendor-related variables such as DEB_VENDOR:
#include /usr/share/dpkg/vendor.mk
# Package-related variables such as DEB_DISTRIBUTION
#include /usr/share/dpkg/pkg-info.mk
#
# You may alternatively set them susing a simple script such as:
# DEB_VENDOR ?= $(shell dpkg-vendor --query  Vendor)
#
# These are rarely used code. (END)
#

### main packaging script based on post dh7 syntax
%:
        dh $@

# debmake generated override targets
# Use "make prefix=/usr" (override prefix=/usr/local in Makefile)
#override_dh_auto_install:
#       dh_auto_install -- prefix=/usr

# Do not install python .pyc .pyo if they exist
#override_dh_install:
#       dh_install --list-missing -X.pyc -X.pyo

# Multiarch package requires library files to be installed to
# /usr/lib/<triplet>/ .  If the build system does not support
# $(DEB_HOST_MULTIARCH), you may need to override some targets such as
# dh_auto_configure or dh_auto_install to use $(DEB_HOST_MULTIARCH) .

這便是使用 dh 命令時標準的 debian/rules 檔案。（某些內容已被註釋，可供後續修改使用。）

這裡的 debian/control 檔案提供了 Debian 套件的主要參數。此時該檔案是由 debmake 命令產生的模板檔案。

debian/control（模板檔案）：. 

[debhello-0.0] $ cat debian/control
Source: debhello
Section: unknown
Priority: optional
Maintainer: "Osamu Aoki" <osamu@debian.org>
Build-Depends:
 debhelper-compat (= 13),
Standards-Version: 4.7.3
Homepage: <insert the upstream URL, if relevant>
Rules-Requires-Root: no
#Vcs-Git: https://salsa.debian.org/debian/debhello.git
#Vcs-Browser: https://salsa.debian.org/debian/<project_site>

Package: debhello
Section: unknown
Architecture: any
Multi-Arch: foreign
Depends:
 ${misc:Depends},
 ${shlibs:Depends},
Description: auto-generated package by debmake
 This Debian binary package was auto-generated by the
 debmake(1) command provided by the debmake package.
 .
 ===== This comes from the unmodified template file =====
 .
 Please edit this template file (debian/control) and other package files
 (debian/*) to make them meet all the requirements of the Debian Policy
 before uploading this package to the Debian archive.
 .
 See
  * https://www.debian.org/doc/manuals/developers-reference/best-pkging-pract...
  * https://www.debian.org/doc/manuals/debmake-doc/ch05.en.html#control
 .
 The synopsis description at the top should be about 60 characters and
 written as a phrase.  No extra capital letters or a final period.  No
 articles — "a", "an", or "the".
 .
 The package description for general-purpose applications should be
 written for a less technical user.  This means that we should avoid
 jargon.  GNOME or KDE is fine but GTK+ is probably not.
 .
 Use the canonical forms of words:
  * Use X Window System, X11, or X; not X Windows, X-Windows, or X Window.
  * Use GTK+, not GTK or gtk.
  * Use GNOME, not Gnome.
  * Use PostScript, not Postscript or postscript.

	警告
	If you leave “Section: unknown” in the template debian/control file unchanged, the lintian error may cause the build to fail.

作為維護者，要製作一個合適的 Debian 套件當然需要對模板內容進行一些手工的調整。

In order to install files as a part of the system files, the $(prefix) value of /usr/local in the Makefile should be overridden to be /usr. This can be accommodated by the following the debian/rules file with the override_dh_auto_install target setting “prefix=/usr”.

debian/rules（維護者版本）：. 

[base_dir] $ cd debhello-0.0
[debhello-0.0] $ vim debian/rules
 ... hack, hack, hack, ...
[debhello-0.0] $ cat debian/rules
#!/usr/bin/make -f
export DH_VERBOSE = 1
export DEB_BUILD_MAINT_OPTIONS = hardening=+all
export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed

%:
        dh $@

override_dh_auto_install:
        dh_auto_install -- prefix=/usr

如上在 debian/rules 檔案中匯出=DH_VERBOSE 環境變數可以強制 debhelper 工具輸出細粒度的構建報告。

The above example did not touch the upstream source to make the proper Debian package. An alternative approach as the maintainer is to modify files in the upstream source. For example, Makefile may be modified to set the $(prefix) value to /usr.

	注意
	The above “節 5.7, “第三步：編輯模板檔案”” using the debian/rules file is the better approach for packaging for this example. But let’s continue on with this alternative approaches as a leaning experience.

Here, the patch file 000-prefix-usr.patch is created using the diff command.

Patch by “diff -u”. 

[base_dir] $ cp -a debhello-0.0 debhello-0.0.orig
[debhello-0.0] $ vim debhello-0.0/Makefile
 ... hack, hack, hack, ...
[base_dir] $ diff -Nru debhello-0.0.orig debhello-0.0 >000-prefix-usr.patch
[base_dir] $ cat 000-prefix-usr.patch
diff -Nru debhello-0.0.orig/Makefile debhello-0.0/Makefile
--- debhello-0.0.orig/Makefile  2026-02-11 09:50:54.416710230 +0000
+++ debhello-0.0/Makefile       2026-02-11 09:50:54.498291151 +0000
@@ -1,4 +1,4 @@
-prefix = /usr/local
+prefix = /usr

 all: src/hello

[base_dir] $ rm -rf debhello-0.0
[base_dir] $ mv -f debhello-0.0.orig debhello-0.0

Please note that the upstream source tree is restored to the original state after generating a patch file 000-prefix-usr.patch.

Here, the patch file 000-prefix-usr.patch is created using the dquilt command.

dquilt is a simple wrapper of the quilt program. The syntax and function of the dquilt command is the same as the quilt(1) command, except for the fact that the generated patch is stored in the debian/patches/ directory.

Patch by dquilt. 

[debhello-0.0] $ dquilt new 000-prefix-usr.patch
Patch debian/patches/000-prefix-usr.patch is now on top
[debhello-0.0] $ dquilt add Makefile
File Makefile added to patch debian/patches/000-prefix-usr.patch
 ... hack, hack, hack, ...
[debhello-0.0] $ head -1 Makefile
prefix = /usr
[debhello-0.0] $ dquilt refresh
Refreshed patch debian/patches/000-prefix-usr.patch
[debhello-0.0] $ dquilt header -e --dep3
 ... edit the DEP-3 patch header with editor
[debhello-0.0] $ tree -a
.
├── .pc
│   ├── .quilt_patches
│   ├── .quilt_series
│   ├── .version
│   ├── 000-prefix-usr.patch
│   │   ├── .timestamp
│   │   └── Makefile
│   └── applied-patches
├── Makefile
├── README.md
├── debian
│   ├── README.Debian
│   ├── README.source
│   ├── changelog
│   ├── clean
│   ├── control
│   ├── copyright
│   ├── dirs
│   ├── docs
│   ├── examples
│   ├── gbp.conf
│   ├── install
│   ├── links
│   ├── manpages
│   ├── patches
│   │   ├── 000-prefix-usr.patch
│   │   └── series
│   ├── rules
│   ├── salsa-ci.yml
│   ├── source
│   │   └── format
│   ├── tests
│   │   └── control
│   ├── upstream
│   │   └── metadata
│   └── watch
└── src
    └── hello.c

9 directories, 30 files
[debhello-0.0] $ cat debian/patches/series
000-prefix-usr.patch
[debhello-0.0] $ cat debian/patches/000-prefix-usr.patch
Description: set prefix=/usr patch
Author: Osamu Aoki <osamu@debian.org>
Index: debhello-0.0/Makefile
===================================================================
--- debhello-0.0.orig/Makefile
+++ debhello-0.0/Makefile
@@ -1,4 +1,4 @@
-prefix = /usr/local
+prefix = /usr

 all: src/hello

Here, Makefile in the upstream source tree doesn’t need to be restored to the original state for the packaging.

	注意
	When generating the Debian source package by dpkg-source via dpkg-buildpackage in the following step of “節 5.8, “Step 4: Building package with debuild””, the dpkg-source command assumes that patches were applied to the upstream source, since the .pc/applied-patches exists.

The upstream source tree can be restored to the original state for the packaging.

The upstream source tree (restored): 

[debhello-0.0] $ dquilt pop -a
Removing patch debian/patches/000-prefix-usr.patch
Restoring Makefile

No patches applied
[debhello-0.0] $ head -1 Makefile
prefix = /usr/local
[debhello-0.0] $ tree -a .pc
.pc
├── .quilt_patches
├── .quilt_series
└── .version

1 directory, 3 files

Here, Makefile is restored and the .pc/applied-patches is missing.