Debian Packaging Primer: A Detailed Guide to debian/control, rules, and changelog

If you have ever tried to package an application into .deb Bao, you will definitely encounter it.debian/ These three files in the directory:control,rules,changelog. They are the "three pillars" of Debian source packages, determining your package What it looks like, how to build it, and how versions iterate.

Before starting the main content of this topic (the postinst, prerm, and postrm maintainer scripts), it is necessary to first establish an understanding of these three core files. This introductory chapter will help you quickly clear up the basic knowledge, and subsequent chapters will not repeat it.

debian/control: the package's "ID card"

control The file defines the software package's metadata and Dependency relationship. It is dpkg and apt The primary file read during installation, upgrade, and uninstallation.

A typical control file

Source: myapp
Section: utils
Priority: optional
Maintainer: Your Name <[email protected]>
Build-Depends: debhelper-compat (= 13), golang-go
Standards-Version: 4.6.2

Package: myapp
Architecture: amd64
Depends: ${shlibs:Depends}, ${misc:Depends}
Description: My awesome application
 A longer description of what this package does.
 It can span multiple lines.

Key field interpretation

field	effect	Remarks
Source	Source package name	Usually the same name as the binary package
Build-Depends	Build-time dependencies	Toolchains and libraries required for the compilation phase
Package	Binary package name	The package name installed by the end user
Architecture	Architecture	amd64,arm64,all(Pure script)
Depends	Runtime dependency	Dependency packages automatically pulled during installation
Description	Package description	The first line is a short description, and the following are long descriptions.

💡Key points:Depends commonly seen in ${shlibs:Depends} and ${misc:Depends} Yes debhelper The automatically generated dependency variables will be replaced with the actual dynamic library dependencies at build time.

debian/rules: the "construction blueprint" for building

rules is a Makefile, tell dpkg-buildpackage How to compile, test, and install your software. It is the entire build process's Core control file.

Simplest rules (using dh)

#!/usr/bin/make -f

%:
    dh $@

That short? Yes!dh Yes debhelper provided automated build system, it will execute a series of standard steps in order:

clean → build → build-arch → build-indep → install → binary-arch → binary-indep → binary

Common override scenarios

In actual projects, you often need to Coverage Some default behaviors. For example, injecting the version number in a Go project:

#!/usr/bin/make -f

%:
    dh $@

override_dh_auto_build:
    go build -ldflags="-X main.Version=$(shell cat VERSION)" -o myapp ./cmd/myapp

Another example: a VUE project needs to be run first.npm run build:

override_dh_auto_build:
    npm install
    npm run build

Common dh commands

Command	Effect
dh_auto_clean	Clean build artifacts
dh_auto_build	Execute build
dh_auto_install	Install to debian/tmp temporary directory
dh_install	Copy the file to the package directory
dh_systemd_enable	Enable the systemd service
dh_systemd_start	Start the systemd service

debian/changelog: the timeline of versions

changelog recorded the software package's Version History and Change Description. It is not only for users to see, but more importantly dpkg Rely on it to determine whether the version is new or old..

Standard format

myapp (1.2.3-1) unstable; urgency=medium

  * Feature: add support for config hot-reload
  * Fix: memory leak in connection pool
  * Update dependencies to latest

 -- Your Name <[email protected]>  Mon, 26 Jun 2026 10:00:00 +0800

Version Number Specification

1.2.3-1 Consists of two parts:

• upstream version:1.2.3(the version of the software itself)

• Debian revision number:-1(which Debian packaging iteration of this upstream version)

Common operations

# View version history
dpkg-parsechangelog

# Generate new version entry (interactive)
dch -i

# Specify version number
dch -v 1.2.4-1 "Release 1.2.4"

# Mark as published
dch -r

The relationship among the troika

Simply put:

• changelog decided on the package Version number

• control defined the package's Dependencies and metadata

• rules commanded How to build this bag

Quickly verify your packaging environment

Run the following command to confirm that the basic tools are installed:

dpkg --version          # dpkg tool
dpkg-buildpackage --version  # build tools
dh --version            # debhelper

If it prompts that it is not installed, execute:

sudo apt install build-essential debhelper devscripts

Summary

file	Core responsibilities	analogy
debian/control	Define dependencies and metadata	Product's "label"
debian/rules	Control the build process	The factory's "production line"
debian/changelog	Manage version history	Product's changelog

Once you have mastered these three files, you will have the basic framework for understanding Debian packaging. In the following chapters, we will delve deeper Maintainer script(postinst, prerm, postrm), that is when the package is on the user's machine Install, upgrade, uninstall the actual execution logic at the time.

Next article preview:Chapter 1: Complete Interpretation and Best Practices of postinst Scripts